# Capawesome

> Capawesome offers enterprise-grade solutions and services designed for teams building cross-platform apps with Capacitor.

Capawesome is an open source organization on [GitHub](https://github.com/capawesome-team) that provides enterprise-grade solutions and services for teams developing cross-platform applications with [Capacitor](https://github.com/ionic-team/capacitor). Capawesome currently maintains almost 200 high-quality [Capacitor SDKs](sdks/capacitor/index.md) with more than **5,000,000 monthly downloads**. Besides that, Capawesome offers a [Cloud](cloud/index.md) solution for Capacitor Live Updates, Native Builds, App Store Publishing, and Automations.

# MCP servers

# MCP Servers

The [Model Context Protocol](https://modelcontextprotocol.io) lets an AI assistant call tools on a server instead of answering from its training data. It can search the current documentation, fetch the page it needs, and act on your account, without you pasting anything into the conversation.

We host three MCP servers, one per part of the stack. All three are remote HTTP servers, so there is nothing to install and nothing to keep up to date, and they work with Claude Code, Claude Desktop, Cursor, VS Code, and any other MCP client.

## Capawesome MCP Server

Searches the Capawesome documentation and blog. With an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) it also exposes the [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) management API: trigger a native build, ship a live update, roll back a channel, or diagnose a failed job. This is the official Capawesome MCP server, maintained by us.

```
https://mcp.capawesome.io/mcp
```

[Set up the Capawesome MCP server](https://capawesome.io/docs/ai/mcp/capawesome/index.md)

## Capacitor MCP Server

Serves the official [Capacitor](https://capacitorjs.com) documentation for v8, v7, v6 and `next`, the official and community plugin list, and the Capacitor posts from the Ionic blog. Free, no token. Unofficial server, maintained by Capawesome and not affiliated with or endorsed by Ionic or OutSystems.

```
https://capacitor-mcp.capawesome.io/mcp
```

[Set up the Capacitor MCP server](https://capawesome.io/docs/ai/mcp/capacitor/index.md)

## Ionic Framework MCP Server

Serves the official [Ionic Framework](https://ionicframework.com) documentation for v9 and v8, including the component API reference and the usage examples for Angular, React, Vue and vanilla JavaScript. Free, no token. Unofficial server, maintained by Capawesome and not affiliated with or endorsed by Ionic or OutSystems.

```
https://ionic-framework-mcp.capawesome.io/mcp
```

[Set up the Ionic Framework MCP server](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md)

## Next steps

- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.
- [Skills](https://capawesome.io/docs/ai/skills/index.md) — on-demand agent skills that automate migrations and Cloud setup.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent.

# Capawesome MCP Server

The Capawesome MCP server connects your AI assistant to Capawesome — the documentation and blog, and your [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) apps, builds, deployments, and devices. It implements the [Model Context Protocol](https://modelcontextprotocol.io), so it works with Claude Code, Claude Desktop, Cursor, VS Code, and any other MCP client.

It's hosted by us — there's nothing to install and nothing to keep up to date:

```
https://mcp.capawesome.io/mcp
```

On its own, the server exposes documentation search, so your assistant answers from the current docs instead of stale training data. Add your API token and enable the Cloud tools, and it also exposes the Capawesome Cloud management surface: trigger an app build, ship a live update, roll back a channel, or diagnose a failed job — without leaving the conversation.

## Authentication

The documentation tools work without authentication. Everything else requires an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md), sent as a bearer token in the `Authorization` header. Create one in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/tokens) — the token is shown only once, so copy it right away.

A token acts on behalf of the account that created it, so the server can do whatever you can do across your organizations and apps. Requests go through the same [Cloud API](https://capawesome.io/docs/cloud/api/index.md) as the CLI, which means the same permissions, [network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md), and rate limits apply.

Keep tokens secret

Never commit a token to version control. Store it in a secret manager or an environment variable, and revoke it in the Console if it might have leaked.

## Setup

### AI-Assisted Setup (Recommended)

The fastest way to connect the server is with an AI coding assistant. First, add the [Capawesome skills](https://github.com/capawesome-team/skills) to your project:

```
npx skills add capawesome-team/skills --skill capawesome-mcp
```

Then use the following prompt in your preferred AI tool (e.g. [Claude Code](https://www.anthropic.com/claude-code), [Cursor](https://www.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot)):

```
Use the `capawesome-mcp` skill from `capawesome-team/skills` to help me set up the Capawesome MCP server in my project.
```

The assistant will pick the [toolsets](#toolsets) you need, walk you through creating an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md), write the configuration for your MCP client, and verify that the tools are available.

### Manual Setup

If you prefer to set things up manually, add the server to your MCP client and restart it. The examples use `?toolsets=all`, which registers the documentation tools plus — once you add a token — the Capawesome Cloud tools. Replace `YOUR_TOKEN` with your API token, or drop the `Authorization` header for documentation tools only.

Run the following command in your project:

```
claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp?toolsets=all" \
  --header "Authorization: Bearer YOUR_TOKEN"
```

Add `--scope user` to make the server available in every project instead of just the current one.

Go to **Settings → Connectors → Add custom connector** and enter:

- **Name**: `Capawesome`
- **URL**: `https://mcp.capawesome.io/mcp`

The same connector works on [claude.ai](https://claude.ai). It cannot send an `Authorization` header, so it gives you the documentation tools only.

To reach the Capawesome Cloud tools as well, start the server through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) instead. Add the following to your `claude_desktop_config.json` (open it via **Settings → Developer → Edit Config**):

```
{
  "mcpServers": {
    "capawesome": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.capawesome.io/mcp?toolsets=all",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

The header value comes from `env` because a header with spaces isn't passed through reliably on the command line.

The badge installs the server without a token. To add one, or to set things up by hand, add the following to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` to use the server everywhere:

```
{
  "mcpServers": {
    "capawesome": {
      "url": "https://mcp.capawesome.io/mcp?toolsets=all",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=capawesome&config=%7B%22name%22%3A%22capawesome%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.capawesome.io%2Fmcp%3Ftoolsets%3Dall%22%7D)

The link installs the server without a token. To add one, or to set things up by hand, add the following to `.vscode/mcp.json` in your project:

```
{
  "servers": {
    "capawesome": {
      "type": "http",
      "url": "https://mcp.capawesome.io/mcp?toolsets=all",
      "headers": {
        "Authorization": "Bearer ${input:capawesome-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "capawesome-token",
      "type": "promptString",
      "description": "Capawesome Cloud API token",
      "password": true
    }
  ]
}
```

VS Code prompts for the token the first time the server starts and stores it securely, so the file stays safe to commit.

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```
{
  "mcpServers": {
    "capawesome": {
      "serverUrl": "https://mcp.capawesome.io/mcp?toolsets=all",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Add the server to your Zed `settings.json`:

```
{
  "context_servers": {
    "capawesome": {
      "url": "https://mcp.capawesome.io/mcp?toolsets=all",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Clients that cannot connect to a remote server over HTTP can run the [`@capawesome/mcp`](https://www.npmjs.com/package/@capawesome/mcp) package, which proxies stdio to the hosted server:

```
{
  "mcpServers": {
    "capawesome": {
      "command": "npx",
      "args": ["-y", "@capawesome/mcp"],
      "env": {
        "CAPAWESOME_TOKEN": "YOUR_TOKEN",
        "CAPAWESOME_MCP_TOOLSETS": "all"
      }
    }
  }
}
```

Requires Node.js 22 or later. Omit `env` to use the documentation tools only. The proxy is configured with these environment variables instead of a header and query parameters:

| Variable                  | Purpose                                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CAPAWESOME_TOKEN`        | API token, sent as `Authorization: Bearer`. Optional; without it only the documentation tools are available.                                            |
| `CAPAWESOME_MCP_TOOLSETS` | Comma-separated toolsets to register, sent as `?toolsets=`. Use `cloud` for every Capawesome Cloud toolset or `all` for everything. Defaults to `docs`. |
| `CAPAWESOME_MCP_READONLY` | Set to `true` to skip every tool that writes or deletes, sent as `?readonly=true`.                                                                      |
| `CAPAWESOME_MCP_URL`      | Override the endpoint. For development only.                                                                                                            |

Once connected, ask your assistant something like *"Which channels does my app have?"* or *"Why did my last iOS build fail?"* to check that the tools are available.

## Toolsets

By default the server registers just the public `docs` toolset — documentation and blog search, no token needed. To add [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) management, use `?toolsets=all`, which registers the documentation tools alongside every Cloud toolset:

```
https://mcp.capawesome.io/mcp?toolsets=all
```

That's what most setups want — documentation search plus the full Cloud surface. If you don't need documentation search, `?toolsets=cloud` registers the Cloud toolsets on their own.

To register a smaller, sharper set — every tool takes up context in your assistant, and fewer tools makes it pick the right one more often — name the specific toolsets you need, keeping `docs` for documentation search:

```
https://mcp.capawesome.io/mcp?toolsets=docs,cloud-apps,cloud-app-builds,cloud-app-deployments
```

Put the URL in quotes when you pass query parameters on the command line, otherwise your shell interprets them.

Add `?readonly=true` to register read-only tools only. Nothing can then be created, changed, or deleted — a good fit for a shared or unattended setup.

### Documentation

Registered by default. Needs no token.

| Toolset | Tools | Description                        |
| ------- | ----- | ---------------------------------- |
| `docs`  | 3     | Search the documentation and blog. |

### Cloud

Opt-in with `?toolsets=cloud` (all of them) or by name. Each requires an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md). A toolset named `cloud-app-*` acts on a single app, so its tools all take an app ID.

| Toolset                    | Tools | Description                                                                                                                    |
| -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------ |
| `cloud-app-automations`    | 5     | Manage [automations](https://capawesome.io/docs/cloud/automations/index.md) that build on Git events.                          |
| `cloud-app-builds`         | 5     | Trigger [app builds](https://capawesome.io/docs/cloud/native-builds/index.md) and share them.                                  |
| `cloud-app-certificates`   | 5     | Manage [signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) and provisioning profiles. |
| `cloud-app-channels`       | 5     | Manage [live update channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md).                                |
| `cloud-app-configurations` | 5     | Manage [native configurations](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md).                 |
| `cloud-app-deployments`    | 4     | Deploy builds to channels and app stores, and roll back.                                                                       |
| `cloud-app-destinations`   | 5     | Manage [app store destinations](https://capawesome.io/docs/cloud/app-store-publishing/index.md).                               |
| `cloud-app-devices`        | 5     | Inspect devices and control which update they receive.                                                                         |
| `cloud-app-environments`   | 5     | Manage build [environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md), variables, and secrets.     |
| `cloud-app-repository`     | 3     | Link an app to a Git repository, and see which one it uses.                                                                    |
| `cloud-apps`               | 4     | Create, list, and update apps.                                                                                                 |
| `cloud-git`                | 6     | Manage the Git connections of an organization and browse their repositories.                                                   |
| `cloud-jobs`               | 5     | Track, cancel, and diagnose builds and deployments, and read their logs.                                                       |
| `cloud-license-keys`       | 6     | Manage [license keys](https://capawesome.io/docs/cloud/license-keys/index.md) for Insiders and Enterprise SDKs.                |
| `cloud-organizations`      | 10    | Identify yourself, list your organizations (and the IDs other tools need), and manage members and invitations.                 |
| `cloud-teams`              | 5     | Manage teams and their apps and members.                                                                                       |

## Tool reference

All 86 tools, grouped by toolset. Each one carries MCP annotations that mark it as read-only or destructive, which is what clients use to decide when to ask you for confirmation before running a tool.

### docs

| Tool              | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `search_docs`     | Search the Capawesome documentation and blog.           |
| `get_doc_page`    | Fetch a documentation or blog page as Markdown.         |
| `list_blog_posts` | List the 20 most recent posts from the Capawesome blog. |

### cloud-app-automations

| Tool                          | Description                     |
| ----------------------------- | ------------------------------- |
| `cloud_list_app_automations`  | List the automations of an app. |
| `cloud_get_app_automation`    | Get a single automation.        |
| `cloud_create_app_automation` | Create an automation.           |
| `cloud_update_app_automation` | Update an automation.           |
| `cloud_delete_app_automation` | Delete an automation.           |

### cloud-app-builds

| Tool                           | Description                                                  |
| ------------------------------ | ------------------------------------------------------------ |
| `cloud_list_app_builds`        | List builds, filtered by platform or build number.           |
| `cloud_get_app_build`          | Get a build with its job status and artifact download links. |
| `cloud_create_app_build`       | Start a build from a Git ref or a ZIP URL.                   |
| `cloud_create_app_build_share` | Create a share link with QR code for a build.                |
| `cloud_delete_app_build_share` | Revoke a share link immediately.                             |

### cloud-app-certificates

| Tool                           | Description                                                      |
| ------------------------------ | ---------------------------------------------------------------- |
| `cloud_list_app_certificates`  | List the signing certificates of an app, including their expiry. |
| `cloud_get_app_certificate`    | Get a single certificate.                                        |
| `cloud_create_app_certificate` | Upload a signing certificate and optional provisioning profiles. |
| `cloud_update_app_certificate` | Update the name, passwords, or type of a certificate.            |
| `cloud_delete_app_certificate` | Delete a certificate.                                            |

### cloud-app-channels

| Tool                       | Description                         |
| -------------------------- | ----------------------------------- |
| `cloud_list_app_channels`  | List the channels of an app.        |
| `cloud_get_app_channel`    | Get a single channel.               |
| `cloud_create_app_channel` | Create a channel.                   |
| `cloud_update_app_channel` | Rename, pause, or resume a channel. |
| `cloud_delete_app_channel` | Delete a channel.                   |

### cloud-app-configurations

| Tool                             | Description                                                               |
| -------------------------------- | ------------------------------------------------------------------------- |
| `cloud_list_app_configurations`  | List the native configurations of an app.                                 |
| `cloud_get_app_configuration`    | Get a single native configuration.                                        |
| `cloud_create_app_configuration` | Create a native configuration.                                            |
| `cloud_update_app_configuration` | Update the display name, name, or package name of a native configuration. |
| `cloud_delete_app_configuration` | Delete a native configuration.                                            |

### cloud-app-deployments

| Tool                          | Description                                                                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `cloud_list_app_deployments`  | List deployments, filtered by build, channel, or destination.                                                                            |
| `cloud_get_app_deployment`    | Get a deployment with its job status.                                                                                                    |
| `cloud_create_app_deployment` | Deploy a build to a channel or an app store destination, optionally with release notes. Deploying an earlier build is how you roll back. |
| `cloud_update_app_deployment` | Adjust the rollout percentage of a deployment.                                                                                           |

### cloud-app-destinations

| Tool                           | Description                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `cloud_list_app_destinations`  | List the app store destinations of an app.                                                              |
| `cloud_get_app_destination`    | Get a single destination.                                                                               |
| `cloud_create_app_destination` | Connect an App Store Connect, Google Play, Huawei AppGallery, or Firebase App Distribution destination. |
| `cloud_update_app_destination` | Update a destination, such as its Google Play track, TestFlight beta groups, or App Review submission.  |
| `cloud_delete_app_destination` | Delete a destination.                                                                                   |

### cloud-app-devices

| Tool                      | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `cloud_list_app_devices`  | List the devices registered for an app.                   |
| `cloud_get_app_device`    | Get a single device.                                      |
| `cloud_probe_app_device`  | Check which live update a device would receive right now. |
| `cloud_update_app_device` | Assign or clear the channel a device is pinned to.        |
| `cloud_delete_app_device` | Delete a device. It re-registers on its next sync.        |

### cloud-app-environments

| Tool                           | Description                                                       |
| ------------------------------ | ----------------------------------------------------------------- |
| `cloud_list_app_environments`  | List the environments of an app.                                  |
| `cloud_get_app_environment`    | Get a single environment.                                         |
| `cloud_create_app_environment` | Create an environment.                                            |
| `cloud_update_app_environment` | Rename an environment and set or unset its variables and secrets. |
| `cloud_delete_app_environment` | Delete an environment.                                            |

### cloud-app-repository

| Tool                          | Description                                |
| ----------------------------- | ------------------------------------------ |
| `cloud_get_app_repository`    | Show which repository an app is linked to. |
| `cloud_set_app_repository`    | Link an app to a repository.               |
| `cloud_delete_app_repository` | Unlink an app from its repository.         |

### cloud-apps

| Tool               | Description                       |
| ------------------ | --------------------------------- |
| `cloud_create_app` | Create an app in an organization. |
| `cloud_list_apps`  | List the apps of an organization. |
| `cloud_get_app`    | Get a single app.                 |
| `cloud_update_app` | Update an app.                    |

### cloud-git

| Tool                          | Description                                             |
| ----------------------------- | ------------------------------------------------------- |
| `cloud_list_git_connections`  | List the Git connections of an organization.            |
| `cloud_get_git_connection`    | Get a single Git connection.                            |
| `cloud_create_git_connection` | Create a token or HTTP(S) Git connection.               |
| `cloud_update_git_connection` | Update a Git connection.                                |
| `cloud_delete_git_connection` | Delete a Git connection.                                |
| `cloud_list_git_repositories` | Browse the repositories available through a connection. |

### cloud-jobs

| Tool                 | Description                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| `cloud_list_jobs`    | List the jobs of an organization, filtered by status.                      |
| `cloud_get_job`      | Get a single job.                                                          |
| `cloud_get_job_logs` | Read the last lines of a build or deployment log, whatever the job status. |
| `cloud_cancel_job`   | Cancel a running build or deployment.                                      |
| `cloud_diagnose_job` | Fetch the AI failure summary of a failed job.                              |

### cloud-license-keys

| Tool                       | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| `cloud_list_license_keys`  | List the license keys of an organization.                    |
| `cloud_get_license_key`    | Get a single license key.                                    |
| `cloud_create_license_key` | Create a license key and assign packages to it.              |
| `cloud_update_license_key` | Update a license key.                                        |
| `cloud_rotate_license_key` | Rotate a license key. The old key stops working immediately. |
| `cloud_delete_license_key` | Delete a license key.                                        |

### cloud-organizations

| Tool                        | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `cloud_get_current_user`    | Show which account the token belongs to.              |
| `cloud_list_organizations`  | List the organizations you have access to.            |
| `cloud_get_organization`    | Get a single organization.                            |
| `cloud_create_organization` | Create an organization, optionally with a trial code. |
| `cloud_update_organization` | Update an organization.                               |
| `cloud_list_members`        | List the members of an organization.                  |
| `cloud_delete_member`       | Remove a member from an organization.                 |
| `cloud_list_invitations`    | List the pending invitations of an organization.      |
| `cloud_create_invitation`   | Invite someone to an organization with a given role.  |
| `cloud_delete_invitation`   | Revoke a pending invitation.                          |

### cloud-teams

| Tool                | Description                                       |
| ------------------- | ------------------------------------------------- |
| `cloud_list_teams`  | List the teams of an organization.                |
| `cloud_get_team`    | Get a team with its apps and members.             |
| `cloud_create_team` | Create a team.                                    |
| `cloud_update_team` | Rename a team and add or remove apps and members. |
| `cloud_delete_team` | Delete a team.                                    |

## Working with secrets

A few tools accept sensitive values — environment secrets, signing certificates, and app store credentials. Anything you pass to a tool becomes part of the conversation and is sent to your AI provider, and it may end up in chat history or logs you don't control.

Use the CLI for production secrets

Set production secrets, upload signing certificates, and connect store destinations with the [CLI](https://capawesome.io/docs/cloud/cli/index.md) or the [Console](https://console.cloud.capawesome.io) instead. Keep the MCP server for reading and for values you'd be fine seeing in a transcript.

## Rate limits

The endpoint is limited to **100 requests per minute per IP**. Requests over the limit are answered with `429 Too Many Requests`; retry after a short wait.

## Privacy

Your IP address is processed for rate limiting only. Queries and tool arguments are not stored, not logged beyond Cloudflare's standard edge logs, and never used for training. Your API token is used to authenticate against the Capawesome Cloud API on your behalf and is not stored by the server. See our [privacy policy](https://capawesome.io/legal/privacy-policy/) for details.

## Related servers

- [Capacitor MCP Server](https://capawesome.io/docs/ai/mcp/capacitor/index.md) — the official Capacitor documentation, the official and community plugin list, and the Capacitor posts from the Ionic blog.
- [Ionic Framework MCP Server](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md) — the official Ionic Framework documentation, its component API reference, and the usage examples for Angular, React, Vue and vanilla JavaScript.

## Next steps

- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.
- [Skills](https://capawesome.io/docs/ai/skills/index.md) — on-demand agent skills that automate migrations and Cloud setup.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent.

# Capacitor MCP Server

The Capacitor MCP server gives your AI assistant the current [Capacitor](https://capacitorjs.com) documentation for v8, v7, v6 and `next`, the official and community plugin list, and the Capacitor posts from the Ionic blog — so it stops guessing plugin APIs and CLI flags. It implements the [Model Context Protocol](https://modelcontextprotocol.io), so it works with Claude Code, Claude Desktop, Cursor, VS Code, and any other MCP client.

Unofficial server

This server is maintained by Capawesome and is not affiliated with or endorsed by Ionic or OutSystems. It serves the official Capacitor documentation, © the Ionic team and licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Endpoint

The server is hosted by us and ready to use. No account, no token, no installation:

```
https://capacitor-mcp.capawesome.io/mcp
```

## Setup

### AI-Assisted Setup (Recommended)

The fastest way to connect the server is with an AI coding assistant. First, add the [Capawesome skills](https://github.com/capawesome-team/skills) to your project:

```
npx skills add capawesome-team/skills --skill capacitor-mcp
```

Then use the following prompt in your preferred AI tool (e.g. [Claude Code](https://www.anthropic.com/claude-code), [Cursor](https://www.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot)):

```
Use the `capacitor-mcp` skill from `capawesome-team/skills` to help me set up the Capacitor MCP server in my project.
```

The assistant will detect your MCP client, write the configuration, verify that the tools are available, and pass the [documentation version](#versions) that matches the `@capacitor/core` version in your project.

### Manual Setup

If you prefer to set things up manually, add the server to your MCP client and restart it.

Run the following command in your project:

```
claude mcp add --transport http capacitor https://capacitor-mcp.capawesome.io/mcp
```

Add `--scope user` to make the server available in every project instead of just the current one.

Go to **Settings → Connectors → Add custom connector** and enter:

- **Name**: `Capacitor`
- **URL**: `https://capacitor-mcp.capawesome.io/mcp`

The same connector works on [claude.ai](https://claude.ai).

Or add the following to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` to use the server everywhere:

```
{
  "mcpServers": {
    "capacitor": {
      "url": "https://capacitor-mcp.capawesome.io/mcp"
    }
  }
}
```

[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=capacitor&config=%7B%22name%22%3A%22capacitor%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fcapacitor-mcp.capawesome.io%2Fmcp%22%7D)

Or add the following to `.vscode/mcp.json` in your project:

```
{
  "servers": {
    "capacitor": {
      "type": "http",
      "url": "https://capacitor-mcp.capawesome.io/mcp"
    }
  }
}
```

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```
{
  "mcpServers": {
    "capacitor": {
      "serverUrl": "https://capacitor-mcp.capawesome.io/mcp"
    }
  }
}
```

Add the server to your Zed `settings.json`:

```
{
  "context_servers": {
    "capacitor": {
      "url": "https://capacitor-mcp.capawesome.io/mcp"
    }
  }
}
```

Clients that cannot connect to a remote server over HTTP can run the [`@capawesome/capacitor-mcp`](https://www.npmjs.com/package/@capawesome/capacitor-mcp) package, which proxies stdio to the hosted server:

```
{
  "mcpServers": {
    "capacitor": {
      "command": "npx",
      "args": ["-y", "@capawesome/capacitor-mcp"]
    }
  }
}
```

Requires Node.js 22 or later.

Once connected, ask your assistant something like *"How do I configure deep links in Capacitor 8?"* or *"Which Capacitor plugin should I use to pick a file?"* to check that the tools are available.

## Tools

| Tool              | Description                                                                         | Parameters                                        |
| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------- |
| `search_docs`     | Search the documentation by keyword. The starting point for any Capacitor question. | `query` (required), `section`, `version`, `limit` |
| `get_doc_page`    | Fetch a full documentation page returned by `search_docs` as Markdown.              | `url` (required), `version`                       |
| `list_plugins`    | List official and community Capacitor plugins.                                      | `query`, `source`, `limit`                        |
| `list_blog_posts` | List the 10 most recent Capacitor-tagged posts from the Ionic blog.                 | —                                                 |

`list_plugins` takes a `source` of `official`, `community` or `all`. Official plugins come from the Capacitor documentation, community plugins from [awesome-capacitorjs](https://github.com/capawesome-team/awesome-capacitorjs). Results are ranked official plugins first, then Capawesome plugins, then the remaining community plugins. The server discloses that ranking in its response, so your assistant can weigh it.

## Versions

The documentation is available for Capacitor **v8** (default), **v7**, **v6** and **next**. Pass the `version` parameter to `search_docs` and `get_doc_page` to target a specific version.

Set it to the major version of `@capacitor/core` in your project. On Capacitor 7, `version: "v7"` keeps the answers on the APIs and CLI flags that release actually has.

## Documentation source

The index is rebuilt daily from [`ionic-team/capacitor-docs`](https://github.com/ionic-team/capacitor-docs) at a pinned commit. The documentation content is © the Ionic team, licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), converted from MDX to Markdown for delivery over MCP and otherwise served unmodified in substance. Blog excerpts come from the [Ionic blog](https://ionic.io/blog) and link to the original post.

The client package is open source at [`capawesome-team/capacitor-mcp`](https://github.com/capawesome-team/capacitor-mcp).

## Rate limits

The endpoint is limited to **100 requests per minute per IP**. Requests over the limit are answered with `429 Too Many Requests`; retry after a short wait.

## Privacy

Your IP address is processed for rate limiting only. Queries and tool arguments are not stored, not logged beyond Cloudflare's standard edge logs, and never used for training. See our [privacy policy](https://capawesome.io/legal/privacy-policy/) for details.

## Related servers

- [Ionic Framework MCP Server](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md) — the same for the Ionic Framework documentation, its component API reference, and the usage examples for Angular, React, Vue and vanilla JavaScript.
- [Capawesome MCP Server](https://capawesome.io/docs/ai/mcp/capawesome/index.md) — the Capawesome documentation and the Capawesome Cloud management API for Live Updates, Native Builds, and App Store Publishing.

## Next steps

- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.
- [Skills](https://capawesome.io/docs/ai/skills/index.md) — on-demand agent skills that automate migrations and Cloud setup.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent.

# Ionic Framework MCP Server

The Ionic Framework MCP server gives your AI assistant the current [Ionic Framework](https://ionicframework.com) documentation for v9 and v8, including the component API reference and the usage examples for Angular, React, Vue and vanilla JavaScript, plus the Ionic blog. It implements the [Model Context Protocol](https://modelcontextprotocol.io), so it works with Claude Code, Claude Desktop, Cursor, VS Code, and any other MCP client. For the story behind the server and what it changes in practice, read [Ionic Framework MCP Server for Your AI Assistant](https://capawesome.io/blog/ionic-framework-mcp-server/index.md).

Unofficial server

This server is maintained by Capawesome and is not affiliated with or endorsed by Ionic or OutSystems. It serves the official Ionic Framework documentation, © the Ionic team and licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Endpoint

The server is hosted by us and ready to use. No account, no token, no installation:

```
https://ionic-framework-mcp.capawesome.io/mcp
```

## Setup

### AI-Assisted Setup (Recommended)

The fastest way to connect the server is with an AI coding assistant. First, add the [Capawesome skills](https://github.com/capawesome-team/skills) to your project:

```
npx skills add capawesome-team/skills --skill ionic-framework-mcp
```

Then use the following prompt in your preferred AI tool (e.g. [Claude Code](https://www.anthropic.com/claude-code), [Cursor](https://www.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot)):

```
Use the `ionic-framework-mcp` skill from `capawesome-team/skills` to help me set up the Ionic Framework MCP server in my project.
```

The assistant will detect your MCP client, write the configuration, verify that the tools are available, and pass the [documentation version](#versions) and the framework that match your project.

### Manual Setup

If you prefer to set things up manually, add the server to your MCP client and restart it.

Run the following command in your project:

```
claude mcp add --transport http ionic-framework https://ionic-framework-mcp.capawesome.io/mcp
```

Add `--scope user` to make the server available in every project instead of just the current one.

Go to **Settings → Connectors → Add custom connector** and enter:

- **Name**: `Ionic Framework`
- **URL**: `https://ionic-framework-mcp.capawesome.io/mcp`

The same connector works on [claude.ai](https://claude.ai).

Or add the following to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` to use the server everywhere:

```
{
  "mcpServers": {
    "ionic-framework": {
      "url": "https://ionic-framework-mcp.capawesome.io/mcp"
    }
  }
}
```

[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=ionic-framework&config=%7B%22name%22%3A%22ionic-framework%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fionic-framework-mcp.capawesome.io%2Fmcp%22%7D)

Or add the following to `.vscode/mcp.json` in your project:

```
{
  "servers": {
    "ionic-framework": {
      "type": "http",
      "url": "https://ionic-framework-mcp.capawesome.io/mcp"
    }
  }
}
```

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```
{
  "mcpServers": {
    "ionic-framework": {
      "serverUrl": "https://ionic-framework-mcp.capawesome.io/mcp"
    }
  }
}
```

Add the server to your Zed `settings.json`:

```
{
  "context_servers": {
    "ionic-framework": {
      "url": "https://ionic-framework-mcp.capawesome.io/mcp"
    }
  }
}
```

Clients that cannot connect to a remote server over HTTP can run the [`@capawesome/ionic-framework-mcp`](https://www.npmjs.com/package/@capawesome/ionic-framework-mcp) package, which proxies stdio to the hosted server:

```
{
  "mcpServers": {
    "ionic-framework": {
      "command": "npx",
      "args": ["-y", "@capawesome/ionic-framework-mcp"]
    }
  }
}
```

Requires Node.js 22 or later.

Once connected, ask your assistant something like *"Which events does `ion-modal` emit?"* or *"Show me an inline `ion-datetime` in React"* to check that the tools are available.

## Tools

| Tool                  | Description                                                                               | Parameters                                                |
| --------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `search_docs`         | Search the documentation by keyword. The starting point for any Ionic Framework question. | `query` (required), `section`, `version`, `limit`         |
| `get_doc_page`        | Fetch a full documentation page returned by `search_docs` as Markdown.                    | `url` (required), `version`                               |
| `list_components`     | List Ionic Framework components with their API reference.                                 | `query`, `version`, `limit`                               |
| `get_component_usage` | Read the official usage examples for a component, per framework.                          | `component` (required), `example`, `framework`, `version` |
| `list_blog_posts`     | List recent posts from the Ionic blog.                                                    | —                                                         |

A component page returned by `get_doc_page` carries the full API reference: properties, events, methods, CSS shadow parts, CSS custom properties, and slots. That is what an assistant needs to style a component correctly instead of inventing a class name.

`get_component_usage` returns the official examples from the documentation. Pass `framework` as `angular`, `react`, `vue` or `javascript` to get the variant that matches your project.

## Versions

The documentation is available for Ionic Framework **v9** (default) and **v8**. Pass the `version` parameter to target a specific version.

Set it to the major version of `@ionic/core`, `@ionic/angular`, `@ionic/react` or `@ionic/vue` in your project, so the properties and events your assistant suggests exist in the release you ship.

## Documentation source

The index is rebuilt daily from [`ionic-team/ionic-docs`](https://github.com/ionic-team/ionic-docs) at a pinned commit. The documentation content is © the Ionic team, licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), converted from MDX to Markdown for delivery over MCP and otherwise served unmodified in substance. Blog excerpts come from the [Ionic blog](https://ionic.io/blog) and link to the original post.

The client package is open source at [`capawesome-team/ionic-framework-mcp`](https://github.com/capawesome-team/ionic-framework-mcp).

## Rate limits

The endpoint is limited to **100 requests per minute per IP**. Requests over the limit are answered with `429 Too Many Requests`; retry after a short wait.

## Privacy

Your IP address is processed for rate limiting only. Queries and tool arguments are not stored, not logged beyond Cloudflare's standard edge logs, and never used for training. See our [privacy policy](https://capawesome.io/legal/privacy-policy/) for details.

## Related servers

- [Capacitor MCP Server](https://capawesome.io/docs/ai/mcp/capacitor/index.md) — the same for the Capacitor documentation, the official and community plugin list, and the Capacitor posts from the Ionic blog.
- [Capawesome MCP Server](https://capawesome.io/docs/ai/mcp/capawesome/index.md) — the Capawesome documentation and the Capawesome Cloud management API for Live Updates, Native Builds, and App Store Publishing.

## Next steps

- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.
- [Skills](https://capawesome.io/docs/ai/skills/index.md) — on-demand agent skills that automate migrations and Cloud setup.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent.
# AI

# AI

Capawesome is built to work well with AI agents and large language models. Whether you're using an AI coding assistant in your editor or a script that calls an LLM, this section collects the resources that help those tools understand Capawesome and carry out real tasks — installing plugins, migrating versions, and setting up Capawesome Cloud.

There are two sides to AI at Capawesome:

- **Bring your own AI** — feed our machine-readable docs, agent skills, and editor rules to whatever assistant you already use, or connect it to our [MCP servers](https://capawesome.io/docs/ai/mcp/index.md) to let it read the current docs and manage Capawesome Cloud directly. That's what the pages below cover.
- **AI inside the product** — [Cloud Assist](https://capawesome.io/docs/cloud/assist/index.md) brings AI directly into the Console, including [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md) for diagnosing failed builds and deployments.

## Resources

- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.
- [MCP Servers](https://capawesome.io/docs/ai/mcp/index.md) — connect Claude, Cursor, or any MCP client to the [Capawesome](https://capawesome.io/docs/ai/mcp/capawesome/index.md) docs and your Cloud apps, and to the [Capacitor](https://capawesome.io/docs/ai/mcp/capacitor/index.md) and [Ionic Framework](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md) documentation.
- [Skills](https://capawesome.io/docs/ai/skills/index.md) — on-demand agent skills that automate complex tasks like migrations and Cloud setup.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent with Capawesome conventions.
- [Guides](https://capawesome.io/docs/ai/guides/index.md) — practical walkthroughs for AI-assisted development.

# Agent Skills

Agent skills are folders of instructions that an AI coding agent loads on demand, whenever the task at hand matches the skill's description. They follow the [Agent Skills specification](https://agentskills.io/specification), so the same folder works in Claude Code, Cursor, GitHub Copilot, Codex, and every other agent that implements it. [Capawesome Skills](https://github.com/capawesome-team/skills) is an open source collection of 30 such skills for Capacitor, the Ionic Framework, and Capawesome Cloud. Each one spells out the exact file paths, diffs, and commands a task needs, so the agent follows a documented procedure instead of guessing.

## Install

Add the plugin marketplace, then install the plugins you need:

```
claude plugin marketplace add capawesome-team/skills
claude plugin install capacitor-core@capawesome-skills
```

| Plugin                   | Skills                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `capacitor-core`         | App creation, development, upgrades, expert reference, plugin setup, desktop platforms, and MCP server setup. |
| `capacitor-frameworks`   | Angular, React, and Vue patterns for Capacitor.                                                               |
| `capacitor-integrations` | Push notifications (FCM) and in-app purchases.                                                                |
| `capacitor-plugin-dev`   | Create, upgrade, and add SPM support to Capacitor plugins.                                                    |
| `capawesome-cloud`       | MCP server, CLI setup, native builds, live updates, and app store publishing.                                 |
| `ionic-core`             | App creation, development, upgrades, expert reference, and MCP server setup.                                  |
| `ionic-frameworks`       | Angular, React, and Vue patterns for Ionic.                                                                   |
| `ionic-migrations`       | Migrations from Ionic Appflow and the Ionic Enterprise SDK.                                                   |

The plugins cover every skill except `capgo-cloud-migration`. Install that one with the `skills` CLI.

```
npx skills add capawesome-team/skills --agent cursor
```

The [`skills` CLI](https://skills.sh) installs into any supported agent and asks which ones to use:

```
npx skills add capawesome-team/skills
```

Pass `--agent` to skip that prompt — for example `--agent claude-code`, `--agent codex`, `--agent github-copilot`, or `--agent windsurf`. Add `--global` to install the skills for every project instead of the current one.

To add a single skill instead of all of them, name it with `--skill`:

```
npx skills add capawesome-team/skills --skill capawesome-cloud
```

The skills are updated as Capacitor, Ionic, and Capawesome Cloud change. Pull the latest version with:

```
npx skills update
```

## Available skills

### Capacitor

| Skill                          | Description                                                                                                | Install command                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `capacitor-angular`            | Angular patterns and best practices for Capacitor apps.                                                    | `npx skills add capawesome-team/skills --skill capacitor-angular`            |
| `capacitor-app-creation`       | Create a new Capacitor app with platform setup.                                                            | `npx skills add capawesome-team/skills --skill capacitor-app-creation`       |
| `capacitor-app-development`    | Core concepts, CLI usage, app configuration, and troubleshooting.                                          | `npx skills add capawesome-team/skills --skill capacitor-app-development`    |
| `capacitor-app-spm-migration`  | Migrate an app's iOS dependencies from CocoaPods to SPM.                                                   | `npx skills add capawesome-team/skills --skill capacitor-app-spm-migration`  |
| `capacitor-app-upgrades`       | Upgrade a Capacitor app to a newer major version.                                                          | `npx skills add capawesome-team/skills --skill capacitor-app-upgrades`       |
| `capacitor-expert`             | Comprehensive Capacitor reference and starting point.                                                      | `npx skills add capawesome-team/skills --skill capacitor-expert`             |
| `capacitor-in-app-purchases`   | Set up in-app purchases and subscriptions.                                                                 | `npx skills add capawesome-team/skills --skill capacitor-in-app-purchases`   |
| `capacitor-mcp`                | Connect an MCP client to the [Capacitor MCP server](https://capawesome.io/docs/ai/mcp/capacitor/index.md). | `npx skills add capawesome-team/skills --skill capacitor-mcp`                |
| `capacitor-platforms`          | Add the Electron and Tauri desktop platforms.                                                              | `npx skills add capawesome-team/skills --skill capacitor-platforms`          |
| `capacitor-plugin-development` | Create and maintain Capacitor plugins from scratch.                                                        | `npx skills add capawesome-team/skills --skill capacitor-plugin-development` |
| `capacitor-plugin-spm-support` | Add Swift Package Manager support to a plugin.                                                             | `npx skills add capawesome-team/skills --skill capacitor-plugin-spm-support` |
| `capacitor-plugin-upgrades`    | Upgrade a Capacitor plugin to a newer major version.                                                       | `npx skills add capawesome-team/skills --skill capacitor-plugin-upgrades`    |
| `capacitor-plugins`            | Install and configure plugins from official and community sources.                                         | `npx skills add capawesome-team/skills --skill capacitor-plugins`            |
| `capacitor-push-notifications` | Set up push notifications with Firebase Cloud Messaging.                                                   | `npx skills add capawesome-team/skills --skill capacitor-push-notifications` |
| `capacitor-react`              | React patterns and best practices for Capacitor apps.                                                      | `npx skills add capawesome-team/skills --skill capacitor-react`              |
| `capacitor-vue`                | Vue patterns and best practices for Capacitor apps.                                                        | `npx skills add capawesome-team/skills --skill capacitor-vue`                |

### Ionic Framework

| Skill                   | Description                                                                                                            | Install command                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `ionic-angular`         | Angular patterns for Ionic — navigation, lifecycle, and forms.                                                         | `npx skills add capawesome-team/skills --skill ionic-angular`         |
| `ionic-app-creation`    | Create a new Ionic app with Capacitor integration.                                                                     | `npx skills add capawesome-team/skills --skill ionic-app-creation`    |
| `ionic-app-development` | Core concepts, component reference, layout, and theming.                                                               | `npx skills add capawesome-team/skills --skill ionic-app-development` |
| `ionic-app-upgrades`    | Upgrade an Ionic app to a newer major version.                                                                         | `npx skills add capawesome-team/skills --skill ionic-app-upgrades`    |
| `ionic-expert`          | Comprehensive Ionic Framework reference and starting point.                                                            | `npx skills add capawesome-team/skills --skill ionic-expert`          |
| `ionic-framework-mcp`   | Connect an MCP client to the [Ionic Framework MCP server](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md). | `npx skills add capawesome-team/skills --skill ionic-framework-mcp`   |
| `ionic-react`           | React patterns for Ionic — components, routing, and lifecycle hooks.                                                   | `npx skills add capawesome-team/skills --skill ionic-react`           |
| `ionic-vue`             | Vue patterns for Ionic — components, navigation, and composables.                                                      | `npx skills add capawesome-team/skills --skill ionic-vue`             |

### Capawesome

| Skill              | Description                                                                                                                                                                                                                                          | Install command                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `capawesome-cli`   | Install, authenticate, and use the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).                                                                                                                                                  | `npx skills add capawesome-team/skills --skill capawesome-cli`   |
| `capawesome-cloud` | Set up [native builds](https://capawesome.io/docs/cloud/native-builds/index.md), [live updates](https://capawesome.io/docs/cloud/live-updates/index.md), and [app store publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md). | `npx skills add capawesome-team/skills --skill capawesome-cloud` |
| `capawesome-mcp`   | Connect an MCP client to the [Capawesome MCP server](https://capawesome.io/docs/ai/mcp/capawesome/index.md).                                                                                                                                         | `npx skills add capawesome-team/skills --skill capawesome-mcp`   |

### Migrations

| Skill                            | Description                                                           | Install command                                                                |
| -------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `capgo-cloud-migration`          | Migrate from Capgo to Capawesome Cloud.                               | `npx skills add capawesome-team/skills --skill capgo-cloud-migration`          |
| `ionic-appflow-migration`        | Migrate from Ionic Appflow to Capawesome Cloud.                       | `npx skills add capawesome-team/skills --skill ionic-appflow-migration`        |
| `ionic-enterprise-sdk-migration` | Migrate from Ionic Enterprise SDK plugins to Capawesome alternatives. | `npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration` |

## Skills or the MCP servers

The skills and the [MCP servers](https://capawesome.io/docs/ai/mcp/index.md) cover different ground, so most projects use both. The skills detect a connected server and prefer it for documentation, falling back to their bundled reference files when none is connected.

|                                                             | MCP servers                                  | Skills          |
| ----------------------------------------------------------- | -------------------------------------------- | --------------- |
| Capawesome plugin, CLI, and Cloud documentation             | ✅ always current                            | ✅ bundled      |
| Capacitor Firebase and Capacitor MLKit plugin documentation | ✅ always current                            | ✅ bundled      |
| Official and community Capacitor plugins                    | ✅ Capacitor MCP server                      | ✅              |
| RevenueCat plugins                                          | ❌                                           | ✅              |
| Capacitor and Ionic upgrade guides                          | ✅ Capacitor and Ionic Framework MCP servers | ✅ step by step |
| Ionic Appflow, Ionic Enterprise SDK, and Capgo migrations   | ❌                                           | ✅              |
| Managing Capawesome Cloud apps, builds, and deployments     | ✅                                           | via the CLI     |
| Works without a network round trip                          | ❌                                           | ✅              |

## Example prompts

Once the skills are installed, describe the task and the agent picks the matching skill on its own. An upgrade across two major versions:

```
Upgrade my Capacitor app from version 6 to version 8.
```

A plugin setup, including the native configuration for Android and iOS:

```
Install and configure the @capawesome/capacitor-file-picker plugin in my project.
```

A Capawesome Cloud feature end to end:

```
Set up Capacitor Live Updates with Capawesome Cloud in my project.
```

To pin the agent to one skill, name it: *"Use the `capawesome-cloud` skill from `capawesome-team/skills` to set up Live Updates in my project."*

## FAQ

### Which AI agents can use the skills?

Any agent that supports the Agent Skills specification. The `skills` CLI installs into more than 70 of them, including Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and OpenCode.

### Do I need a Capawesome Cloud account?

Only for the skills that manage Capawesome Cloud. The Capacitor, Ionic Framework, and plugin skills work without an account.

### Do the skills require an MCP server?

No. Every skill ships with its own reference files and works offline. When one of the [MCP servers](https://capawesome.io/docs/ai/mcp/index.md) is connected, the skills use it for documentation so the answers stay current between releases. The `capacitor-mcp`, `ionic-framework-mcp`, and `capawesome-mcp` skills set the servers up for you.

### Are the skills free and open source?

Yes. They are published under the MIT license in the [Capawesome Skills repository](https://github.com/capawesome-team/skills), and contributions are welcome.

### How do I keep the skills up to date?

Run `npx skills update`. Claude Code plugin installations update through `claude plugin update`.

### Where are the skills installed?

The `skills` CLI writes to the agent's skills directory in your project — `.claude/skills/` for Claude Code, `.agents/skills/` for Cursor, Codex, and GitHub Copilot. Pass `--global` to install them to your home directory instead.

## Next steps

- [MCP Servers](https://capawesome.io/docs/ai/mcp/index.md) — connect Claude, Cursor, or any MCP client to the Capawesome, Capacitor, and Ionic Framework documentation.
- [Editor Rules](https://capawesome.io/docs/ai/rules/index.md) — always-on project rules that keep generated code consistent.
- [LLMs](https://capawesome.io/docs/ai/llms/index.md) — `llms.txt` files and Markdown endpoints that make the docs readable by any model.

# Editor Rules

Editor rules are project files that AI coding assistants read on every interaction — standing conventions that keep generated code consistent. Unlike [skills](https://capawesome.io/docs/ai/skills/index.md) (which an agent runs on demand), rules are always-on context.

Most assistants support a project rules file:

- **AGENTS.md** — a cross-tool convention read by many agents.
- **Cursor** — `.cursor/rules/*.mdc`.
- **Windsurf** — `.windsurfrules`.
- **Claude Code** — `CLAUDE.md`.

## Starter rules

Add a file like the following (e.g. `AGENTS.md`) to your project root and adapt it:

```
# Project rules

- This is a Capacitor app. Prefer Capacitor APIs and Capawesome plugins.
- Use the Capawesome CLI (`@capawesome/cli`) for Capawesome Cloud tasks.
- For OTA updates, use `@capawesome/capacitor-live-update` and publish via
  `apps:liveupdates:upload`. Keep web bundles binary-compatible with the
  installed native version.
- Never commit secrets, signing keys, or API tokens.
```

## Skills vs. rules

- **Rules** are standing conventions the agent always reads.
- **[Skills](https://capawesome.io/docs/ai/skills/index.md)** are on-demand procedures the agent runs for a specific task.

Use both: rules to set the baseline, skills to execute complex tasks like migrations or Cloud setup.

# LLMs

Capawesome provides documentation resources designed for large language models and AI applications, formatted for the [llms.txt](https://llmstxt.org/) initiative. These files give an AI assistant accurate, up-to-date context about Capawesome's SDKs and Cloud — point your tool at one of the URLs below, or paste its contents in, so answers and generated code reflect the current docs instead of stale training data.

## Documentation Files

- **Index File**

  ______________________________________________________________________

  A list of all available documentation files.

  [/llms.txt](/docs/llms.txt)

- **Complete Capawesome Documentation**

  ______________________________________________________________________

  Comprehensive coverage including all Capawesome SDKs, Capawesome Cloud, and development workflows.

  [/llms-full.txt](/docs/llms-full.txt)

## Markdown endpoints

Each documentation page can also be accessed as Markdown by appending `/index.md` to the page URL. For example, `https://capawesome.io/docs/sdks/capacitor/` becomes `https://capawesome.io/docs/sdks/capacitor/index.md`.

## MCP servers

For assistants that speak the Model Context Protocol, we host three servers that answer from the current documentation instead of a file you have to keep in sync:

| Server                                                                        | Endpoint                                        | Covers                                                                                                                    |
| ----------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [Capawesome](https://capawesome.io/docs/ai/mcp/capawesome/index.md)           | `https://mcp.capawesome.io/mcp`                 | Official server for the Capawesome documentation and blog, plus the Capawesome Cloud management API.                      |
| [Capacitor](https://capawesome.io/docs/ai/mcp/capacitor/index.md)             | `https://capacitor-mcp.capawesome.io/mcp`       | Unofficial server for the official Capacitor documentation, the plugin list, and the Capacitor posts from the Ionic blog. |
| [Ionic Framework](https://capawesome.io/docs/ai/mcp/ionic-framework/index.md) | `https://ionic-framework-mcp.capawesome.io/mcp` | Unofficial server for the official Ionic Framework documentation, the component API reference, and the usage examples.    |

## Agent skills

For automated development workflows, Capawesome also publishes [AI agent skills](https://capawesome.io/docs/ai/skills/index.md) — install them with `npx skills add capawesome-team/skills`.

# Guides

Practical guides for building with Capawesome using AI agents.

## Set up your AI assistant

1. Add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project: `npx skills add capawesome-team/skills`.
1. Add [editor rules](https://capawesome.io/docs/ai/rules/index.md) so your assistant follows your project's conventions.
1. Make the docs available to your assistant — see [LLMs](https://capawesome.io/docs/ai/llms/index.md) for the `llms.txt` files and Markdown endpoints.

## Common AI-assisted tasks

- **Set up Capawesome Cloud** — ask your assistant to use the `capawesome-cloud` skill to set up Live Updates, Native Builds, or App Store Publishing.
- **Migrate between major versions** — use the migration skills to upgrade a Capacitor app or plugin.
- **Diagnose a failed build** — use [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md) in the Console, then hand the diagnosis to your local agent to apply the fix.

> More step-by-step guides are on the way.
# SDKs

# Capacitor Plugins

Capacitor plugins let you access native device features and third-party SDKs from your web-based app with a single JavaScript API that works across Android, iOS, and the Web.

This page lists our Capacitor plugins — part of a collection of over 100 Capacitor SDKs with more than 5 million monthly downloads. Browse by category below to find the right plugin for your app, and open its page for installation steps, supported platforms, and the full API reference.

## Browse plugins by category

### Authentication & Security

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/index.md) — Verify app and device integrity using Play Integrity and App Attest.
- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/index.md) — Read tracking status, request permission, and access the IDFA on iOS.
- [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/index.md) — Sign in with Apple on Android, iOS, and Web.
- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) — Face ID, fingerprint, and device-credential authentication.
- [Facebook Sign-In](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/index.md) — Sign in users with their Facebook account, including Limited Login on iOS.
- [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/index.md) — Sign in with Google on Android, iOS, and Web.
- [Intune](https://capawesome.io/docs/sdks/capacitor/intune/index.md) — Enforce Microsoft Intune app protection policies (MAM) with MSAL authentication.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) — OAuth 2.0 and OpenID Connect with PKCE and token refresh.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/index.md) — Create and authenticate with passkeys based on the WebAuthn standard.
- [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/index.md) — Save passwords to the platform credential store after in-app login.
- [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/index.md) — Check and request device permissions through one unified API.
- [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/index.md) — Hide sensitive content in the app switcher and block screenshots.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/index.md) — Detect rooted and jailbroken devices, emulators, and developer mode.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) — Securely store sensitive data like tokens and passwords.
- [Vault](https://capawesome.io/docs/sdks/capacitor/vault/index.md) — Store key/value pairs in lockable, biometric-protected vaults.

### Payments & Monetization

- [AdMob](https://capawesome.io/docs/sdks/capacitor/admob/index.md) — Monetize your app with banner, interstitial, rewarded, and app open ads.
- [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) — Native in-app purchases and subscriptions with StoreKit 2 and Google Play Billing.
- [Superwall](https://capawesome.io/docs/sdks/capacitor/superwall/index.md) — Manage paywalls and subscriptions with the Superwall SDK.
- [Square Mobile Payments](https://capawesome.io/docs/sdks/capacitor/square-mobile-payments/index.md) — Accept in-person payments with the Square SDK.

### Media & Audio

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) — Play audio through the device speakers with background support.
- [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) — Record audio from the device microphone.
- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/index.md) — Configure and observe the iOS audio session, output routing, and interruptions.
- [Exif](https://capawesome.io/docs/sdks/capacitor/exif/index.md) — Losslessly read, write, and strip EXIF image metadata including HEIC.
- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) — Show media controls and metadata on the lock screen.
- [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/index.md) — Edit photos with filters, cropping, and annotations.
- [Cloudinary](https://capawesome.io/docs/sdks/capacitor/cloudinary/index.md) — Upload files directly from the filesystem to Cloudinary.
- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/index.md) — Headless crop, resize, rotate, flip and HEIC-to-JPEG image conversion.
- [RealtimeKit](https://capawesome.io/docs/sdks/capacitor/realtimekit/index.md) — Add real-time audio, video, and chat to your app.
- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) — Transcribe speech into text (speech-to-text).
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) — Synthesize speech from text (text-to-speech).
- [YouTube Player](https://capawesome.io/docs/sdks/capacitor/youtube-player/index.md) — Embed and control inline YouTube players.

### Scanning

- [Barcode Scanner](https://capawesome.io/docs/sdks/capacitor/barcode-scanner/index.md) — Scan barcodes and QR codes with the camera or from images.
- [Document Scanner](https://capawesome.io/docs/sdks/capacitor/document-scanner/index.md) — Scan documents with automatic edge detection and JPEG or PDF output.

### Files & Storage

- [Asset Manager](https://capawesome.io/docs/sdks/capacitor/asset-manager/index.md) — Read and copy files from the native app bundle.
- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/index.md) — Compress images and other files.
- [File Manager](https://capawesome.io/docs/sdks/capacitor/file-manager/index.md) — Read, write, copy, and move files and directories with persistent folder access.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/index.md) — Open files like PDF, DOCX, and XLSX in their default app.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/index.md) — Let users pick files, images, or videos from the device.
- [File Transfer](https://capawesome.io/docs/sdks/capacitor/file-transfer/index.md) — Download and upload files with progress, pause and resume, and background support.
- [PDF Annotator](https://capawesome.io/docs/sdks/capacitor/pdf-annotator/index.md) — Let users annotate PDF documents with the native markup tools.
- [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/index.md) — Generate paginated PDF files from HTML content or a URL.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/index.md) — Display PDF documents in a fullscreen native viewer.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/index.md) — Zip and unzip files and directories, with encryption support.

### Databases

- [libSQL](https://capawesome.io/docs/sdks/capacitor/libsql/index.md) — Work with libSQL databases in your app.
- [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) — Access encrypted SQLite databases with migrations and transactions.

### Device & Sensors

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/index.md) — Read acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/index.md) — Read air pressure and altitude from the barometer sensor.
- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/index.md) — Read the battery level, state, and low power mode, and listen for changes.
- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) — Communicate with BLE devices, including headless tasks.
- [Calendar](https://capawesome.io/docs/sdks/capacitor/calendar/index.md) — Create, read, update, and delete calendars and events with recurrence support.
- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/index.md) — Read the device compass heading with live updates and true north on iOS.
- [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) — Read, write, and select device contacts.
- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/index.md) — Read device model, OS, memory, and per-install identifier.
- [Flic](https://capawesome.io/docs/sdks/capacitor/flic/index.md) — Connect and interact with Flic smart buttons.
- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/index.md) — Geocode and reverse-geocode addresses and coordinates.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/index.md) — Read the device's gyroscope sensor with real-time rotation rate measurements.
- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/index.md) — Trigger impacts, notifications, vibrations, and custom haptic patterns.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/index.md) — Read network status and type, and listen for changes.
- [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) — Read, write, and emulate NFC tags.
- [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/index.md) — Count steps and track distance traveled.
- [Proximity Sensor](https://capawesome.io/docs/sdks/capacitor/proximity-sensor/index.md) — Read the device proximity sensor with real-time measurement updates.
- [Shake](https://capawesome.io/docs/sdks/capacitor/shake/index.md) — Detect physical shake gestures with configurable sensitivity.
- [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/index.md) — Detect silent mode, read the ringer mode, and listen for changes.
- [SIM](https://capawesome.io/docs/sdks/capacitor/sim/index.md) — Read SIM card and carrier information such as name and country code.
- [Thermal State](https://capawesome.io/docs/sdks/capacitor/thermal-state/index.md) — Read the device thermal state before the OS throttles your app.
- [Torch](https://capawesome.io/docs/sdks/capacitor/torch/index.md) — Toggle the device flashlight.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/index.md) — Control the volume and observe hardware volume button presses.
- [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) — Manage Wi-Fi connectivity and network connections.
- [Zeroconf](https://capawesome.io/docs/sdks/capacitor/zeroconf/index.md) — Discover and advertise services on the local network via mDNS/DNS-SD.

### Location

- [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/index.md) — Track the device location in the background with native HTTP sync.
- [Geofences](https://capawesome.io/docs/sdks/capacitor/geofences/index.md) — Monitor circular regions and receive transitions, even while the app is terminated.

### Health & Fitness

- [Health](https://capawesome.io/docs/sdks/capacitor/health/index.md) — Read and write health and workout data via Health Connect and HealthKit.

### App Experience & UI

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/index.md) — Present native action sheets with styled and destructive buttons.
- [Age Signals](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) — Retrieve age-assurance signals to gate sensitive content.
- [Alarm](https://capawesome.io/docs/sdks/capacitor/alarm/index.md) — Create real system alarms and timers via AlarmKit.
- [App Icon](https://capawesome.io/docs/sdks/capacitor/app-icon/index.md) — Change the app icon at runtime by switching between alternate icons.
- [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/index.md) — Manage the app's language override independently of the device language.
- [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/index.md) — Check whether an app can open and launch it.
- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/index.md) — Request in-app store reviews and ratings.
- [App Shortcuts](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/index.md) — Add home-screen shortcuts for quick actions.
- [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/index.md) — Run tasks after the app moves to the background.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/index.md) — Set and clear the app icon badge count.
- [Clipboard](https://capawesome.io/docs/sdks/capacitor/clipboard/index.md) — Read and write clipboard text, HTML, images, and URLs.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/index.md) — Show a native date and time picker.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/index.md) — Show native alert, confirm, and prompt dialogs.
- [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/index.md) — Hide and show the iOS home indicator for fullscreen experiences.
- [In-App Browser](https://capawesome.io/docs/sdks/capacitor/in-app-browser/index.md) — Open URLs in the external browser, system browser, or embedded web view.
- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/index.md) — Keep the device screen awake and prevent it from sleeping.
- [Localization](https://capawesome.io/docs/sdks/capacitor/localization/index.md) — Read the user's preferred locales, time zone, and regional formatting.
- [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/index.md) — Open the native email composer prefilled with recipients, subject, and attachments.
- [MapLibre](https://capawesome.io/docs/sdks/capacitor/maplibre/index.md) — Render native MapLibre maps with markers, polylines, and GeoJSON layers.
- [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/index.md) — Launch navigation apps with turn-by-turn directions to a destination.
- [Node.js](https://capawesome.io/docs/sdks/capacitor/nodejs/index.md) — Run a full Node.js runtime in your app.
- [Option Picker](https://capawesome.io/docs/sdks/capacitor/option-picker/index.md) — Let the user pick an option from a list with a native picker.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/index.md) — Open the native phone dialer prefilled with a number.
- [PixLive](https://capawesome.io/docs/sdks/capacitor/pixlive/index.md) — Display augmented reality content with the PixLive SDK by Vidinoti.
- [Printer](https://capawesome.io/docs/sdks/capacitor/printer/index.md) — Print HTML, PDFs, files, and web views.
- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/index.md) — Read, set, and reset the app's screen brightness.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/index.md) — Lock the screen to portrait, landscape, or any mode.
- [Screenshot](https://capawesome.io/docs/sdks/capacitor/screenshot/index.md) — Capture and save screenshots.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/index.md) — Open native app, notification, and system settings screens.
- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/index.md) — Receive text, links, and files shared from other apps.
- [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/index.md) — Open the native SMS composer prefilled with recipients and a body.
- [Tab Bar](https://capawesome.io/docs/sdks/capacitor/tab-bar/index.md) — Show a native iOS tab bar with Liquid Glass over the web view.
- [Text Interaction](https://capawesome.io/docs/sdks/capacitor/text-interaction/index.md) — Enable or disable WebView text selection and callout menus on iOS.
- [Text Zoom](https://capawesome.io/docs/sdks/capacitor/text-zoom/index.md) — Read and control the WebView text zoom level.
- [Toast](https://capawesome.io/docs/sdks/capacitor/toast/index.md) — Show native toast notifications with position and duration.
- [Wallet](https://capawesome.io/docs/sdks/capacitor/wallet/index.md) — Add passes to Apple Wallet and Google Wallet from your app.

### Accessibility

- [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/index.md) — Read the user's system accessibility preferences like font scale and reduce motion.
- [Screen Reader](https://capawesome.io/docs/sdks/capacitor/screen-reader/index.md) — Detect screen readers and post accessibility announcements.

### App Updates

- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/index.md) — Check for and prompt users to install app store updates.
- [Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) — Ship over-the-air updates with auto-update and rollback.

### Android

- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/index.md) — Manage battery optimization and Doze exemptions.
- [Android Dark Mode Support](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/index.md) — Add dark mode support via the prefers-color-scheme media feature.
- [Android Edge-to-Edge Support](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) — Enable edge-to-edge display and style the system bars.
- [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/index.md) — Run foreground services with notifications.
- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/index.md) — Launch arbitrary Android intents, start activities, and read their results.
- [Android SMS Retriever](https://capawesome.io/docs/sdks/capacitor/android-sms-retriever/index.md) — OTP autofill via the SMS User Consent and Phone Number Hint APIs.
- [Google Play Services](https://capawesome.io/docs/sdks/capacitor/google-play-services/index.md) — Check whether Google Play Services is available and prompt the user to install or update it.
- [Light Sensor](https://capawesome.io/docs/sdks/capacitor/light-sensor/index.md) — Read real-time ambient light illuminance in lux via event listeners.
- [Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/index.md) — Read MDM-managed app configuration settings.
- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/index.md) — Customize the Android navigation bar.
- [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/index.md) — Detect an outdated Android System WebView and guide users to update.

### Platforms

- [Electron](https://capawesome.io/docs/sdks/capacitor/electron/index.md) — Build, run, and package desktop apps for macOS, Windows, and Linux.
- [Tauri](https://capawesome.io/docs/sdks/capacitor/tauri/index.md) — Build lean, secure desktop apps with tiny binaries for macOS, Windows, and Linux.

### Wearables

- [Watch](https://capawesome.io/docs/sdks/capacitor/watch/index.md) — Exchange messages, user info, and state with Apple Watch and Wear OS apps.

### Analytics & Feedback

- [Formbricks](https://capawesome.io/docs/sdks/capacitor/formbricks/index.md) — Run surveys and collect user feedback with Formbricks.
- [Grafana Faro](https://capawesome.io/docs/sdks/capacitor/grafana-faro/index.md) — Send logs, errors, and crash reports to Grafana Faro.
- [Install Referrer](https://capawesome.io/docs/sdks/capacitor/install-referrer/index.md) — Read install attribution data from Play Install Referrer and Apple Ad Services.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) — Track events and user interactions with PostHog.
- [Singular](https://capawesome.io/docs/sdks/capacitor/singular/index.md) — Attribute app installs and track events, revenue and deep links with Singular.
- [TikTok App Events](https://capawesome.io/docs/sdks/capacitor/tiktok-app-events/index.md) — Track installs, purchases and custom events for TikTok ad campaigns.

### Customer Support & Chat

- [Crisp](https://capawesome.io/docs/sdks/capacitor/crisp/index.md) — Add the Crisp chatbox, helpdesk, and push notifications to your app.
- [Intercom](https://capawesome.io/docs/sdks/capacitor/intercom/index.md) — Present the Intercom Messenger with identity verification and push notifications.

### AI

- [LLM](https://capawesome.io/docs/sdks/capacitor/llm/index.md) — Run on-device AI with Gemini Nano and Apple Intelligence.

### Firebase

A dedicated suite of [Firebase plugins](https://capawesome.io/docs/sdks/capacitor/firebase/index.md) covers Analytics, Authentication, Crashlytics, Cloud Firestore, Cloud Messaging, Cloud Storage, Remote Config, and more.

### ML Kit

A dedicated suite of [ML Kit plugins](https://capawesome.io/docs/sdks/capacitor/mlkit/index.md) adds on-device machine learning, including barcode scanning, document scanning, face detection, translation, and selfie segmentation.

## FAQ

### What are Capacitor plugins?

Capacitor plugins are packages that expose native Android, iOS, and Web functionality through a unified JavaScript API. They let you call platform features — such as the camera, biometrics, or Bluetooth — from the same codebase, without writing native code yourself. To learn more about the underlying framework, see the [official Capacitor documentation](https://capacitorjs.com/docs).

### Are these Capacitor plugins free?

Most plugins are open source and free to use, while a few are offered as paid plugins through [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md). Licensing and pricing are documented on each plugin's page.

### What's the difference between the `@capawesome` and `@capawesome-team` packages?

The npm scope tells you how a plugin is distributed:

- **`@capawesome`** — free plugins published to the public npm registry. Install them directly with npm.
- **`@capawesome-team`** — plugins that are paid or used to be paid. Currently paid plugins are available only through the private Capawesome npm registry and require an Insiders license. Plugins that were paid in the past but are now free are published to both the public npm registry and the Capawesome npm registry, so you can install them from either one.

The [Insiders Getting Started](https://capawesome.io/docs/insiders/getting-started/index.md) guide explains how to configure the Capawesome npm registry.

### Which platforms do the plugins support?

Most plugins support Android and iOS, and many also support the Web. With the [Electron](https://capawesome.io/docs/sdks/capacitor/electron/index.md) and [Tauri](https://capawesome.io/docs/sdks/capacitor/tauri/index.md) platforms, you can also bring your app to the desktop. The supported platforms are listed at the top of each plugin's documentation page.

### How do I get support?

For bugs and feature requests, open an issue on the plugin's GitHub repository. For dedicated help, see our [support options](/docs/support/).

## Next steps

- Explore [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) for Live Updates, Native Builds, and App Store Publishing.
- Browse the [Firebase plugins](https://capawesome.io/docs/sdks/capacitor/firebase/index.md) and [ML Kit plugins](https://capawesome.io/docs/sdks/capacitor/mlkit/index.md).
- View the source on [GitHub](https://github.com/capawesome-team).
- Need help choosing or integrating a plugin? See our [support options](/docs/support/).

# Capacitor Accelerometer Plugin

Capacitor plugin to capture the acceleration force along the x, y, and z axes.

## Features

The Capacitor Accelerometer plugin is one of the most complete motion sensing solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- ⚡ **Real-time measurements**: Continuous accelerometer data with event listeners.
- 📊 **High precision**: Accurate x, y, and z-axis acceleration measurements in G's.
- 🔒 **Permission handling**: Built-in permission management for sensor access.
- 🤝 **Compatibility**: Works alongside the [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) and [Shake](https://capawesome.io/docs/sdks/capacitor/shake/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Accelerometer plugin is typically used whenever an app needs to react to device motion, for example:

- **Shake gestures**: React to rapid device movement, for example to trigger a feedback dialog or undo an action.
- **Motion-based games**: Use the tilt of the device as game input by reading the acceleration along the x, y, and z axes.
- **Fitness and activity tracking**: Analyze continuous motion data to detect movement patterns during workouts.
- **Device orientation**: Determine how the device is being held based on the gravitational force along each axis.

## Compatibility

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

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How this plugin pairs with the Pedometer for fitness tracking and the Gyroscope for motion-based games.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-accelerometer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-accelerometer
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSMotionUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts:

```
<key>NSMotionUsageDescription</key>
<string>The app needs to access the motion activity.</string>
```

## Usage

The following examples show how to check whether the accelerometer is available, request permissions, read the latest measurement, and start and stop continuous measurement updates.

### Check if the accelerometer is available

Check whether the device has an accelerometer sensor before using the other methods:

```
import { Accelerometer } from '@capawesome-team/capacitor-accelerometer';

const isAvailable = async () => {
  const result = await Accelerometer.isAvailable();
  return result.isAvailable;
};
```

### Check and request permissions

Check and request permission to access the accelerometer sensor. On iOS, make sure you have added the `NSMotionUsageDescription` key to your `Info.plist` file (see [Installation](#installation)):

```
import { Accelerometer } from '@capawesome-team/capacitor-accelerometer';

const checkPermissions = async () => {
  const result = await Accelerometer.checkPermissions();
  return result;
};

const requestPermissions = async () => {
  const result = await Accelerometer.requestPermissions();
  return result;
};
```

### Get the latest measurement

Get the most recent measurement from the accelerometer sensor. The acceleration along the x, y, and z axes is returned in G's (gravitational force):

```
import { Accelerometer } from '@capawesome-team/capacitor-accelerometer';

const getMeasurement = async () => {
  const measurement = await Accelerometer.getMeasurement();
  console.log("X: ", measurement.x);
  console.log("Y: ", measurement.y);
  console.log("Z: ", measurement.z);
};
```

### Start and stop measurement updates

Start emitting `measurement` events to receive continuous accelerometer data. When you no longer need updates, stop them and remove your listeners:

```
import { Accelerometer } from '@capawesome-team/capacitor-accelerometer';

const startMeasurementUpdates = async () => {
  await Accelerometer.startMeasurementUpdates();
};

const stopMeasurementUpdates = async () => {
  await Accelerometer.stopMeasurementUpdates();
};

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

## API

- [`getMeasurement()`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getMeasurement()

```
getMeasurement() => Promise<GetMeasurementResult>
```

Get the latest measurement.

This method returns the most recent measurement from the accelerometer sensor.

**Returns:** `Promise<Measurement>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the accelerometer sensor is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Starts emitting `measurement` events.

**Since:** 0.1.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stops emitting `measurement` events.

**Since:** 0.1.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check if the app has permission to access the accelerometer sensor.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to access the accelerometer sensor.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### Measurement

| Prop    | Type     | Description                                           | Since |
| ------- | -------- | ----------------------------------------------------- | ----- |
| **`x`** | `number` | The x-axis acceleration in G's (gravitational force). | 0.1.0 |
| **`y`** | `number` | The y-axis acceleration in G's (gravitational force). | 0.1.0 |
| **`z`** | `number` | The z-axis acceleration in G's (gravitational force). | 0.1.0 |

#### IsAvailableResult

| Prop              | Type      | Description                                                  | Since |
| ----------------- | --------- | ------------------------------------------------------------ | ----- |
| **`isAvailable`** | `boolean` | Whether the accelerometer sensor is available on the device. | 0.1.0 |

#### PermissionStatus

| Prop                | Type                           | Description                             | Since |
| ------------------- | ------------------------------ | --------------------------------------- | ----- |
| **`accelerometer`** | `AccelerometerPermissionState` | The permission status of accelerometer. | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetMeasurementResult

`Measurement`

#### AccelerometerPermissionState

`PermissionState | 'limited'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### MeasurementEvent

`Measurement`

## FAQ

### Which platforms are supported by this plugin?

The Accelerometer plugin supports Android and iOS. You can use the `isAvailable()` method to check whether the accelerometer sensor is available on the current device.

### What unit are the measurements returned in?

The `getMeasurement()` method and the `measurement` event return the acceleration along the x, y, and z axes in G's (gravitational force).

### How do I receive continuous accelerometer updates?

Call `startMeasurementUpdates()` to start emitting `measurement` events and add a listener for the `measurement` event to receive them. When you no longer need updates, call `stopMeasurementUpdates()` and remove your listeners with `removeAllListeners()`. See the [usage example](#start-and-stop-measurement-updates) above.

### Do I need any permissions to use the accelerometer?

The plugin provides the `checkPermissions()` and `requestPermissions()` methods to manage access to the accelerometer sensor. On iOS, you also need to add the `NSMotionUsageDescription` key to your `Info.plist` file as described in the [Installation](#installation) section.

### How can I check if a device has an accelerometer sensor?

Call the `isAvailable()` method. It returns whether the accelerometer sensor is available on the device, so you can check this before calling any other methods.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure, measured in hectopascals (hPa).
- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device's compass heading.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.
- [Shake](https://capawesome.io/docs/sdks/capacitor/shake/): Detect shake gestures on the device.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/accelerometer/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/accelerometer/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/accelerometer/LICENSE).

# Capacitor Accessibility Preferences Plugin

Capacitor plugin for reading the user's system accessibility preferences.

## Features

- ♿ **Accessibility preferences**: Read the user's system accessibility preferences.
- 🔤 **Font scale**: Adapt your typography to the user's preferred text size.
- 🎞️ **Reduce motion**: Disable animations when the user prefers reduced motion.
- 🎨 **Contrast & colors**: React to increased contrast and inverted colors.
- 🌐 **Cross-platform**: Works on Android, iOS, and the Web.
- 🤝 **Compatibility**: Works alongside the [Localization](https://capawesome.io/docs/sdks/capacitor/localization/), [Screen Reader](https://capawesome.io/docs/sdks/capacitor/screen-reader/) and [Text Zoom](https://capawesome.io/docs/sdks/capacitor/text-zoom/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Accessibility Preferences plugin is typically used to adapt an app's user interface to the user's system accessibility settings, for example:

- **Dynamic typography**: Scale your app's font sizes based on the system font scale so text stays readable for users who prefer larger text.
- **Reduced animations**: Disable or simplify animations and transitions when the user prefers reduced motion.
- **High-contrast themes**: Switch to a higher-contrast color scheme when the user has enabled increased contrast.
- **Bold text support**: Render heavier font weights when the user prefers bold text.
- **Color-aware rendering**: Adjust images or charts when the user has enabled inverted colors.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-accessibility-preferences` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following command:

```
npm install @capawesome/capacitor-accessibility-preferences
npx cap sync
```

This plugin does not require any additional permissions or configuration.

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to read the user's system accessibility preferences.

### Read the user's accessibility preferences

Call `getPreferences()` to read all system accessibility preferences at once, such as the font scale, reduce motion, bold text, and contrast settings. Fields that the current platform cannot provide are set to `null` (see [Platform Availability](#platform-availability)):

```
import { AccessibilityPreferences } from '@capawesome/capacitor-accessibility-preferences';

const getPreferences = async () => {
  const preferences = await AccessibilityPreferences.getPreferences();
  return preferences;
};
```

## API

- [`getPreferences()`](#getpreferences)
- [Interfaces](#interfaces)

### getPreferences()

```
getPreferences() => Promise<GetPreferencesResult>
```

Get the user's current system accessibility preferences.

Fields that the current platform cannot provide are set to `null`.

**Returns:** `Promise<GetPreferencesResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetPreferencesResult

| Prop                              | Type      | Description                                                                                                                                                                                                                                                                                                                                           | Since                                                                                                                                                                                                                                            |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`fontScale`**                   | `number`  | The system font scale factor. A value of `1.0` represents the default font size. Values greater than `1.0` indicate that the user prefers larger text, values less than `1.0` smaller text. On iOS, the value is derived from the preferred content size category. On Web, this is always `1.0` because the font scale is not exposed to web content. | 0.1.0                                                                                                                                                                                                                                            |
| **`isBoldTextEnabled`**           | \`boolean | null\`                                                                                                                                                                                                                                                                                                                                                | Whether the user prefers bold text. Returns `null` on platforms where the value cannot be read (Web and Android versions below 12).                                                                                                              |
| **`isHighContrastEnabled`**       | \`boolean | null\`                                                                                                                                                                                                                                                                                                                                                | Whether the user prefers increased contrast. On iOS, this reflects the "Increase Contrast" setting (darker system colors). On Android, this reflects the high text contrast setting. Returns `null` on platforms where the value cannot be read. |
| **`isInvertColorsEnabled`**       | \`boolean | null\`                                                                                                                                                                                                                                                                                                                                                | Whether the user has enabled inverted colors. Returns `null` on Web.                                                                                                                                                                             |
| **`isReduceMotionEnabled`**       | `boolean` | Whether the user prefers reduced motion (fewer animations).                                                                                                                                                                                                                                                                                           | 0.1.0                                                                                                                                                                                                                                            |
| **`isReduceTransparencyEnabled`** | \`boolean | null\`                                                                                                                                                                                                                                                                                                                                                | Whether the user prefers reduced transparency. Only available on iOS. Returns `null` on Android and Web.                                                                                                                                         |

## Platform Availability

Not every preference can be read on every platform. Fields that the current platform cannot provide are set to `null`.

| Field                         | Android      | iOS | Web  |
| ----------------------------- | ------------ | --- | ---- |
| `fontScale`                   | ✅           | ✅  | ⚠️\* |
| `isReduceMotionEnabled`       | ✅           | ✅  | ✅   |
| `isBoldTextEnabled`           | ✅ (API 31+) | ✅  | ❌   |
| `isInvertColorsEnabled`       | ✅           | ✅  | ❌   |
| `isReduceTransparencyEnabled` | ❌           | ✅  | ❌   |
| `isHighContrastEnabled`       | ✅           | ✅  | ✅   |

✅ = available · ❌ = always `null` · ⚠️\* = `fontScale` is always `1.0` on Web because it is not exposed to web content.

On iOS, `fontScale` is derived from the preferred content size category using the following mapping (relative to the default body text size of 17 pt):

| Content size category           | `fontScale` |
| ------------------------------- | ----------- |
| Extra Small                     | 0.82        |
| Small                           | 0.88        |
| Medium                          | 0.94        |
| Large (default)                 | 1.0         |
| Extra Large                     | 1.12        |
| Extra Extra Large               | 1.24        |
| Extra Extra Extra Large         | 1.35        |
| Accessibility Medium            | 1.65        |
| Accessibility Large             | 1.94        |
| Accessibility Extra Large       | 2.35        |
| Accessibility Extra Extra Large | 2.76        |
| Accessibility 3X Large          | 3.12        |

CSS media queries such as `prefers-reduced-motion` and `prefers-contrast` already cover reduce-motion and contrast inside the WebView. The value of this plugin is the fields CSS cannot see (`fontScale`, bold text, inverted colors) and having a single API for your app logic on all platforms.

The screen reader *state* (VoiceOver/TalkBack) is intentionally out of scope. Use the official [`@capacitor/screen-reader`](https://capacitorjs.com/docs/apis/screen-reader) plugin for that.

## FAQ

### Which accessibility preferences can be read on which platforms?

Not every preference is exposed on every platform. The font scale, reduce motion, and high contrast settings are available on Android, iOS, and the Web, while bold text (Android 12+ and iOS), inverted colors (Android and iOS), and reduced transparency (iOS only) are more limited. Check the [Platform Availability](#platform-availability) section for the complete matrix.

### Why is the font scale always 1.0 on the Web?

The system font scale is not exposed to web content, so the plugin cannot read it in a browser. On Android, the plugin returns the system font scale factor, and on iOS the value is derived from the preferred content size category.

### Why are some fields null in the result?

Fields that the current platform cannot provide are set to `null` instead of a fabricated value. For example, `isBoldTextEnabled` is `null` on the Web and on Android versions below 12, and `isReduceTransparencyEnabled` is `null` on Android and Web because it is an iOS-only setting.

### Do I still need this plugin if I use CSS media queries like prefers-reduced-motion?

CSS media queries such as `prefers-reduced-motion` and `prefers-contrast` already cover reduce motion and contrast inside the WebView. The value of this plugin lies in the fields CSS cannot see, such as the font scale, bold text, and inverted colors, and in having a single API for your app logic on all platforms.

### Can this plugin detect whether a screen reader like VoiceOver or TalkBack is running?

No, the screen reader state is intentionally out of scope for this plugin. Use the official [`@capacitor/screen-reader`](https://capacitorjs.com/docs/apis/screen-reader) plugin for that.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Localization](https://capawesome.io/docs/sdks/capacitor/localization/): Read the user's localization preferences, such as preferred locales and time zone.
- [Screen Reader](https://capawesome.io/docs/sdks/capacitor/screen-reader/): Interact with screen readers such as VoiceOver and TalkBack.
- [Text Zoom](https://capawesome.io/docs/sdks/capacitor/text-zoom/): Read and control the WebView text zoom.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/accessibility-preferences/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/accessibility-preferences/LICENSE).

# Capacitor Action Sheet Plugin

Capacitor plugin for native action sheets.

## Features

- 📋 **Action Sheet**: Present a native action sheet with a list of buttons.
- 🎨 **Button Styles**: Highlight destructive actions and pin a cancel button.
- 📝 **Title & Message**: Show a title and message on both Android and iOS.
- 📱 **iPad Ready**: Automatically anchored as a popover on iPad.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Action Sheet plugin is typically used to let the user choose between several actions in a native way, for example:

- **Contextual item actions**: Show options such as upload, share, or delete when the user taps an item in a list.
- **Destructive confirmations**: Highlight irreversible actions like deleting a photo using the destructive button style.
- **Photo source selection**: Ask the user whether to take a new photo or pick an existing one before opening the camera.
- **Cancelable flows**: Pin a cancel button to the sheet so the user can always back out of an action.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-action-sheet` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-action-sheet
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxMaterialVersion` version of `com.google.android.material:material` (default: `1.12.0`)

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to present a native action sheet and read the selected button.

### Show an action sheet

Present a native action sheet with a title, a message, and a list of buttons. Use `ActionSheetButtonStyle.Destructive` to highlight irreversible actions and `ActionSheetButtonStyle.Cancel` to pin a cancel button. The result contains the zero-based index of the selected button. If the user selects the cancel button or dismisses the action sheet, the promise is rejected with the `CANCELED` error code. Only available on Android and iOS:

```
import { ActionSheet, ActionSheetButtonStyle, ErrorCode } from '@capawesome/capacitor-action-sheet';

const showActions = async () => {
  try {
    const { index } = await ActionSheet.showActions({
      title: 'Photo Options',
      message: 'Select an option to perform.',
      options: [
        { title: 'Upload' },
        { title: 'Share' },
        { title: 'Delete', style: ActionSheetButtonStyle.Destructive },
        { title: 'Cancel', style: ActionSheetButtonStyle.Cancel },
      ],
    });
    console.log('Index:', index);
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user canceled the action sheet.');
    }
  }
};
```

## API

- [`showActions(...)`](#showactions)
- [Interfaces](#interfaces)
- [Enums](#enums)

### showActions(...)

```
showActions(options: ShowActionsOptions) => Promise<ShowActionsResult>
```

Show an action sheet with a list of buttons.

If the user selects a button with the [`ActionSheetButtonStyle.Cancel`](#actionsheetbuttonstyle) style or dismisses the action sheet, the promise is rejected with the `CANCELED` error code.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `ShowActionsOptions` |

**Returns:** `Promise<ShowActionsResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ShowActionsResult

| Prop        | Type     | Description                                                           | Since |
| ----------- | -------- | --------------------------------------------------------------------- | ----- |
| **`index`** | `number` | The index of the selected button in the `options` array (zero-based). | 0.1.0 |

#### ShowActionsOptions

| Prop             | Type                  | Description                                                                                                                                                                                                                                                                                                        | Default | Since |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`cancelable`** | `boolean`             | Whether the action sheet can be dismissed by tapping outside of it or pressing the back button. On iOS, this is a system behavior: on iPhone, tapping outside dismisses the action sheet only if it has a button with the `Cancel` style. On iPad, tapping outside always dismisses it. Only available on Android. | `true`  | 0.1.0 |
| **`message`**    | `string`              | The message to display below the title.                                                                                                                                                                                                                                                                            |         | 0.1.0 |
| **`options`**    | `ActionSheetButton[]` | The buttons to display in the action sheet.                                                                                                                                                                                                                                                                        |         | 0.1.0 |
| **`title`**      | `string`              | The title of the action sheet.                                                                                                                                                                                                                                                                                     |         | 0.1.0 |

#### ActionSheetButton

| Prop        | Type                     | Description              | Default                          | Since |
| ----------- | ------------------------ | ------------------------ | -------------------------------- | ----- |
| **`style`** | `ActionSheetButtonStyle` | The style of the button. | `ActionSheetButtonStyle.Default` | 0.1.0 |
| **`title`** | `string`                 | The title of the button. |                                  | 0.1.0 |

### Enums

#### ActionSheetButtonStyle

| Members           | Value           | Description                                                                                  | Since |
| ----------------- | --------------- | -------------------------------------------------------------------------------------------- | ----- |
| **`Cancel`**      | `'CANCEL'`      | A button that cancels the action sheet. It should be the last button in the `options` array. | 0.1.0 |
| **`Default`**     | `'DEFAULT'`     | A button with the default style.                                                             | 0.1.0 |
| **`Destructive`** | `'DESTRUCTIVE'` | A button that indicates a destructive action.                                                | 0.1.0 |

## Migrating from `@capacitor/action-sheet`

This plugin is largely API-compatible with the official [`@capacitor/action-sheet`](https://github.com/ionic-team/capacitor-plugins/tree/main/action-sheet) plugin. The `ActionSheetButtonStyle` enum uses the same values (`DEFAULT`, `DESTRUCTIVE`, `CANCEL`), so no enum changes are required. The following differences apply:

| `@capacitor/action-sheet`                      | `@capawesome/capacitor-action-sheet`                   |
| ---------------------------------------------- | ------------------------------------------------------ |
| `showActions({ title, message, options })`     | `showActions({ title, message, options, cancelable })` |
| Cancel button resolves with its `index`        | Cancel button rejects with the `CANCELED` error code   |
| `message` and button styles ignored on Android | `message` and button styles rendered on Android        |
| `cancelable` not available                     | `cancelable` (default `true`)                          |

## FAQ

### How is this plugin different from other similar plugins?

It presents the platform's own native action sheet on Android and iOS through a fully typed API, rendering the title, message, and button styles — including destructive and cancel styles — consistently on both platforms, and automatically anchoring as a popover on iPad. The result reports the selected button index, a cancellation rejects the promise with the `CANCELED` error code, and the `cancelable` option controls dismissal, all using only official platform APIs. Actively maintained against the latest Capacitor version, it lets a single dependency cover the whole action-sheet story.

### On which platforms can I show an action sheet?

The `showActions(...)` method is only available on Android and iOS, where it presents the native action sheet of the respective platform. On iPad, the action sheet is automatically anchored as a popover.

### How do I know which button the user selected?

The result of `showActions(...)` contains the zero-based `index` of the selected button in the `options` array. If the user selects a button with the `ActionSheetButtonStyle.Cancel` style or dismisses the action sheet, the promise is rejected with the `CANCELED` error code instead.

### Can the user dismiss the action sheet without selecting a button?

Yes. On Android, the action sheet can be dismissed by tapping outside of it or pressing the back button unless you set the `cancelable` option to `false`. On iOS, the `cancelable` option has no effect: on iPhone, tapping outside dismisses the action sheet only if it has a button with the `ActionSheetButtonStyle.Cancel` style, while on iPad, tapping outside always dismisses it. If the action sheet is dismissed, the promise is rejected with the `CANCELED` error code.

### How is this plugin different from the official Capacitor Action Sheet plugin?

This plugin is largely API-compatible with the official `@capacitor/action-sheet` plugin and uses the same `ActionSheetButtonStyle` enum values. In addition, it renders the message and button styles on Android, rejects with the `CANCELED` error code when the user cancels, and supports the `cancelable` option. See the [migration section](#migrating-from-capacitoraction-sheet) for a detailed comparison.

### Can I use this plugin together with the Capawesome Dialog plugin?

Yes, the plugin is designed to work alongside the [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) plugin. Use an action sheet when the user has to choose between several actions, and a dialog for alerts, confirmations, and text input.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Display native alert, confirm, and prompt dialogs.
- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/): Provide haptic feedback such as impacts, notifications, and vibrations.
- [Toast](https://capawesome.io/docs/sdks/capacitor/toast/): Show native toast notifications.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/action-sheet/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/action-sheet/LICENSE).

# Capacitor AdMob Plugin

Capacitor plugin for monetizing your app with Google AdMob ads on Android and iOS. Built on the Android Next-Gen Google Mobile Ads SDK with banner, interstitial, rewarded, rewarded interstitial and app open ads, ad revenue events, and the canonical User Messaging Platform (UMP) consent flow.

⚠️ **Experimental:** This plugin could not be tested extensively yet. Use it with caution in production and [report any issues](https://github.com/capawesome-team/capacitor-plugins/issues) you encounter.

## Features

The Capacitor AdMob plugin is the most complete way to serve Google AdMob ads in a Capacitor app. Here are some of the key features:

- 🚀 **Next-Gen SDK**: Built on the Android Next-Gen Google Mobile Ads SDK and the latest iOS SDK from day one.
- 🖼️ **Banner Ads**: Anchored adaptive, inline adaptive, fixed sizes, and collapsible banners.
- 📐 **Banner Layout Done Right**: Overlay and resize modes with correct edge-to-edge insets, plus inline placement at a frame you measure in CSS pixels.
- 🎬 **Full-Screen Ads**: Interstitial, rewarded, rewarded interstitial, and app open ads with a uniform load/show API.
- 🔁 **App Open Automation**: Automatically load and show app open ads when the app returns to the foreground, with a frequency cap.
- 💰 **Revenue Events**: Receive the paid event of every ad format for your LTV and analytics pipelines.
- 🛡️ **Consent Management**: Canonical User Messaging Platform (UMP) flow with a single method call, privacy options form, and debug geography testing.
- 🔢 **Multiple Instances**: Load and show multiple typed ad instances at the same time, each with its own identifier.
- 🚨 **Typed Errors**: Every rejection carries a typed error code plus the underlying Google Mobile Ads SDK error message.
- 🧪 **Test Device Support**: Register test devices for ads and consent forms.
- 🤝 **Compatibility**: Works hand in hand with the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) and [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The AdMob plugin is typically used to monetize free apps, for example:

- **Banner ads**: Display a persistent banner at the top or bottom of your app, or inline within scrolling content.
- **Interstitial ads**: Show a full-screen ad at natural transition points, such as between levels of a game.
- **Rewarded ads**: Grant users in-app rewards, such as coins or extra lives, for watching an ad.
- **App open ads**: Show an ad when users bring your app back to the foreground.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [Announcing the Capacitor AdMob Plugin](https://capawesome.io/blog/announcing-the-capacitor-admob-plugin/): A tour of the five ad formats on the Google Mobile Ads Next-Gen SDK.
- [How to Handle AdMob GDPR Consent (UMP) in a Capacitor App](https://capawesome.io/blog/how-to-handle-admob-gdpr-consent-in-a-capacitor-app/): The consent flow required before serving ads to EEA users.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-admob` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-admob
npx cap sync
```

### Android

#### AdMob App ID

Add your [AdMob app ID](https://support.google.com/admob/answer/7356431) as a `meta-data` element to the `application` element of your `AndroidManifest.xml` file:

```
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-3940256099942544~3347511713" />
```

**Attention**: The value above is Google's official public **test** app ID. Replace it with your own AdMob app ID before releasing your app. If the `meta-data` element is missing, `initialize(...)` rejects with a clear error message.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### Variables

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

- `$adsMobileSdkVersion` version of `com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk` (default: `1.2.1`)
- `$userMessagingPlatformVersion` version of `com.google.android.ump:user-messaging-platform` (default: `3.2.0`)

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

The plugin uses the **Next-Gen** Google Mobile Ads SDK for Android, which is fetched from Google's Maven repository by your app — it is not bundled with the plugin.

### iOS

#### AdMob App ID

Add the `GADApplicationIdentifier` key with your [AdMob app ID](https://support.google.com/admob/answer/7356431) as value to the `Info.plist` file of your app:

```
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-3940256099942544~1458002511</string>
```

**Attention**: The value above is Google's official public **test** app ID. Replace it with your own AdMob app ID before releasing your app. If the key is missing, `initialize(...)` rejects with a clear error message.

#### SKAdNetwork

Add the [SKAdNetwork identifiers](https://developers.google.com/admob/ios/quick-start#update_your_infoplist) recommended by Google to the `Info.plist` file of your app so that ad attribution works correctly:

```
<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>cstr6suwn9.skadnetwork</string>
  </dict>
</array>
```

**Attention**: The list above only contains Google's own identifier. Google recommends adding the complete list of identifiers from the [official documentation](https://developers.google.com/admob/ios/quick-start#update_your_infoplist), which also covers third-party buyers.

#### App Tracking Transparency

If you want to serve personalized ads, you must request the user's permission to track them across apps and websites. Use the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugin for this and follow Google's recommended order:

1. Call `requestConsent(...)` (see [Usage](#gather-consent-and-initialize-the-sdk)). The UMP consent form includes the App Tracking Transparency context on iOS.
1. Request the tracking permission with the App Tracking Transparency plugin **before** initializing the Google Mobile Ads SDK.
1. Call `initialize(...)`.

This order is important to avoid App Store rejections.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to gather the user's consent, initialize the SDK, show banner, interstitial, rewarded and app open ads, track ad revenue, and test your integration.

### Gather consent and initialize the SDK

Google requires that you gather the user's consent with the User Messaging Platform (UMP) before requesting ads if the user is located in the European Economic Area (EEA), the UK, or a regulated US state. Set up your consent message in the [AdMob console](https://support.google.com/admob/answer/10113207) under **Privacy & messaging** first.

The plugin implements the canonical UMP flow in a single method call. Call `requestConsent(...)` on **every app launch** before initializing the Google Mobile Ads SDK. It requests the latest consent information and shows the consent form if consent is required:

```
import { Admob } from '@capawesome-team/capacitor-admob';

const setupAds = async () => {
  // 1. Gather consent (shows the consent form only if required)
  const { canRequestAds, privacyOptionsRequired } = await Admob.requestConsent();
  // 2. Initialize the Google Mobile Ads SDK
  if (canRequestAds) {
    await Admob.initialize();
  }
  return privacyOptionsRequired;
};
```

If `privacyOptionsRequired` is `true`, you must offer the user a way to change their consent settings, for example from a privacy settings page:

```
const showPrivacyOptions = async () => {
  await Admob.showPrivacyOptionsForm();
};
```

**Note**: The load methods of the plugin reject with the `CONSENT_NOT_GATHERED` error code if ads cannot be requested yet. This prevents ad requests that violate Google's EU User Consent Policy.

### Show a banner ad

The plugin supports three ways to place a banner ad. Choose the one that fits your layout:

| Mode                             | Description                                                                                              | When to use                                                                   |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `mode: 'overlay'` (default)      | The banner ad is displayed on top of the web view, anchored to the top or bottom edge (safe-area aware). | Your layout already reserves space for the banner (e.g. with a fixed footer). |
| `mode: 'resize'`                 | The web view is resized so that the banner ad never overlaps your web content.                           | You want the banner to never cover any content without changing your CSS.     |
| `frame: { x, y, width, height }` | The banner ad is placed at a frame you measure in CSS pixels, e.g. with `getBoundingClientRect()`.       | Inline placement within your content, e.g. between list items.                |

Load and show a banner ad with `showBanner(...)`. Use the returned identifier to hide, resume, or remove the banner ad later:

```
import { Admob, BannerSize } from '@capawesome-team/capacitor-admob';

const showBanner = async () => {
  const { id } = await Admob.showBanner({
    adUnitId: 'ca-app-pub-3940256099942544/6300978111', // Test ad unit ID
    size: BannerSize.AdaptiveBanner,
    position: 'bottom',
  });
  return id;
};
```

For inline placement, measure the anchor element and update the frame on layout changes:

```
import { Admob, BannerSize } from '@capawesome-team/capacitor-admob';

const showInlineBanner = async () => {
  const rect = document.querySelector('#banner-anchor').getBoundingClientRect();
  const { id } = await Admob.showBanner({
    adUnitId: 'ca-app-pub-3940256099942544/6300978111', // Test ad unit ID
    size: BannerSize.InlineAdaptiveBanner,
    frame: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
  });
  // Update the frame when the layout changes (e.g. on scroll or resize)
  window.addEventListener('resize', async () => {
    const newRect = document.querySelector('#banner-anchor').getBoundingClientRect();
    await Admob.setBannerFrame({
      id,
      frame: { x: newRect.x, y: newRect.y, width: newRect.width, height: newRect.height },
    });
  });
};
```

### Show an interstitial ad

Load an interstitial ad in advance and show it at a natural transition point, for example between two levels of a game:

```
import { Admob } from '@capawesome-team/capacitor-admob';

const showInterstitialAd = async () => {
  const { id } = await Admob.loadInterstitialAd({
    adUnitId: 'ca-app-pub-3940256099942544/1033173712', // Test ad unit ID
  });
  await Admob.showInterstitialAd({ id });
};
```

### Show a rewarded ad

Listen for the `rewardEarned` event to grant the reward, then load and show the rewarded ad. Rewarded interstitial ads work the same way with `loadRewardedInterstitialAd(...)` and `showRewardedInterstitialAd(...)`:

```
import { Admob } from '@capawesome-team/capacitor-admob';

const showRewardedAd = async () => {
  await Admob.addListener('rewardEarned', event => {
    console.log(`User earned ${event.amount} ${event.type}`);
  });
  const { id } = await Admob.loadRewardedAd({
    adUnitId: 'ca-app-pub-3940256099942544/5224354917', // Test ad unit ID
  });
  await Admob.showRewardedAd({ id });
};
```

### Show an app open ad

App open ads are shown when users bring your app back to the foreground. You can load and show them manually with `loadAppOpenAd(...)` and `showAppOpenAd(...)`, or let the plugin handle the entire lifecycle:

```
import { Admob } from '@capawesome-team/capacitor-admob';

const enableAppOpenAds = async () => {
  await Admob.enableAppOpenAutoShow({
    adUnitId: 'ca-app-pub-3940256099942544/9257395921', // Test ad unit ID
    minInterval: 14400, // Show at most one ad every 4 hours
  });
};
```

The plugin automatically loads and shows an app open ad every time the app returns to the foreground, honoring the frequency cap. The ad is never shown while a consent form or another full-screen ad is visible.

### Track ad revenue

Listen for the `adRevenuePaid` event to receive the revenue of every ad format, for example for your lifetime value (LTV) and analytics pipelines:

```
import { Admob } from '@capawesome-team/capacitor-admob';

const trackAdRevenue = async () => {
  await Admob.addListener('adRevenuePaid', event => {
    console.log(`Ad revenue: ${event.value} ${event.currencyCode} (${event.precision})`);
  });
};
```

### Test your integration

Always use Google's official public test ad units during development. Using your own ad units during development can lead to your AdMob account being suspended.

| Format                | Android                                  | iOS                                      |
| --------------------- | ---------------------------------------- | ---------------------------------------- |
| Banner                | `ca-app-pub-3940256099942544/6300978111` | `ca-app-pub-3940256099942544/2934735716` |
| Interstitial          | `ca-app-pub-3940256099942544/1033173712` | `ca-app-pub-3940256099942544/4411468910` |
| Rewarded              | `ca-app-pub-3940256099942544/5224354917` | `ca-app-pub-3940256099942544/1712485313` |
| Rewarded Interstitial | `ca-app-pub-3940256099942544/5354046379` | `ca-app-pub-3940256099942544/6978759866` |
| App Open              | `ca-app-pub-3940256099942544/9257395921` | `ca-app-pub-3940256099942544/5575463023` |

You can also register your own devices as test devices with the `testDeviceIds` option of `initialize(...)`.

To test the consent flow, use the `debugGeography` and `testDeviceIds` options of `requestConsent(...)` and reset the consent state with `resetConsent()`:

```
import { Admob, DebugGeography } from '@capawesome-team/capacitor-admob';

const testConsent = async () => {
  await Admob.resetConsent();
  await Admob.requestConsent({
    debugGeography: DebugGeography.Eea,
    testDeviceIds: ['YOUR_TEST_DEVICE_ID'],
  });
};
```

### Handle errors

Every rejection that the plugin can recover from carries a typed error code in `error.code`. Use the `ErrorCode` enum to branch on it:

```
import { Admob, ErrorCode } from '@capawesome-team/capacitor-admob';

const loadInterstitialAd = async () => {
  try {
    return await Admob.loadInterstitialAd({
      adUnitId: 'ca-app-pub-3940256099942544/1033173712', // Test ad unit ID
    });
  } catch (error) {
    if (error.code === ErrorCode.ConsentNotGathered) {
      console.log('Gather the consent with requestConsent() first.');
    } else if (error.code === ErrorCode.NotInitialized) {
      console.log('Initialize the SDK with initialize() first.');
    } else if (error.code === ErrorCode.LoadFailed) {
      console.log('No ad was available:', error.message);
    }
    return undefined;
  }
};
```

The plugin uses the following error codes:

| Code                       | Description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `AD_ALREADY_SHOWING`       | The ad is already showing.                                               |
| `AD_NOT_LOADED`            | No loaded ad was found for the given identifier.                         |
| `APPLICATION_ID_MISSING`   | The AdMob application ID is missing in the native project configuration. |
| `CONSENT_FORM_UNAVAILABLE` | The consent form is not available.                                       |
| `CONSENT_NOT_GATHERED`     | Ads cannot be requested because the consent has not been gathered yet.   |
| `CONSENT_REQUEST_FAILED`   | The consent information could not be requested.                          |
| `LOAD_FAILED`              | The ad could not be loaded.                                              |
| `NOT_INITIALIZED`          | The Google Mobile Ads SDK has not been initialized.                      |

**Note**: The `errorCode` property of the `adFailedToLoad` and `adFailedToShow` events is not an `ErrorCode`. It is the numeric error code reported by the Google Mobile Ads SDK (see [Android](https://developers.google.com/admob/android/reference/com/google/android/gms/ads/AdRequest#constant-summary) and [iOS](https://developers.google.com/admob/ios/reference/enum/GADErrorCode)).

## API

- [`disableAppOpenAutoShow()`](#disableappopenautoshow)
- [`enableAppOpenAutoShow(...)`](#enableappopenautoshow)
- [`hideBanner(...)`](#hidebanner)
- [`initialize(...)`](#initialize)
- [`loadAppOpenAd(...)`](#loadappopenad)
- [`loadInterstitialAd(...)`](#loadinterstitialad)
- [`loadRewardedAd(...)`](#loadrewardedad)
- [`loadRewardedInterstitialAd(...)`](#loadrewardedinterstitialad)
- [`removeBanner(...)`](#removebanner)
- [`requestConsent(...)`](#requestconsent)
- [`resetConsent()`](#resetconsent)
- [`resumeBanner(...)`](#resumebanner)
- [`setApplicationMuted(...)`](#setapplicationmuted)
- [`setApplicationVolume(...)`](#setapplicationvolume)
- [`setBannerFrame(...)`](#setbannerframe)
- [`showAppOpenAd(...)`](#showappopenad)
- [`showBanner(...)`](#showbanner)
- [`showInterstitialAd(...)`](#showinterstitialad)
- [`showPrivacyOptionsForm()`](#showprivacyoptionsform)
- [`showRewardedAd(...)`](#showrewardedad)
- [`showRewardedInterstitialAd(...)`](#showrewardedinterstitialad)
- [`addListener('adClicked', ...)`](#addlisteneradclicked-)
- [`addListener('adDismissed', ...)`](#addlisteneraddismissed-)
- [`addListener('adFailedToLoad', ...)`](#addlisteneradfailedtoload-)
- [`addListener('adFailedToShow', ...)`](#addlisteneradfailedtoshow-)
- [`addListener('adImpressionRecorded', ...)`](#addlisteneradimpressionrecorded-)
- [`addListener('adLoaded', ...)`](#addlisteneradloaded-)
- [`addListener('adRevenuePaid', ...)`](#addlisteneradrevenuepaid-)
- [`addListener('adShowed', ...)`](#addlisteneradshowed-)
- [`addListener('bannerSizeChanged', ...)`](#addlistenerbannersizechanged-)
- [`addListener('rewardEarned', ...)`](#addlistenerrewardearned-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### disableAppOpenAutoShow()

```
disableAppOpenAutoShow() => Promise<void>
```

Disable the automatic loading and showing of app open ads.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### enableAppOpenAutoShow(...)

```
enableAppOpenAutoShow(options: EnableAppOpenAutoShowOptions) => Promise<void>
```

Enable the automatic loading and showing of app open ads when the app is brought back to the foreground.

The ad is never shown while a consent form is visible.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `EnableAppOpenAutoShowOptions` |

**Since:** 0.0.1

______________________________________________________________________

### hideBanner(...)

```
hideBanner(options: HideBannerOptions) => Promise<void>
```

Hide a banner ad without destroying it.

Use `resumeBanner(...)` to show it again.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `HideBannerOptions` |

**Since:** 0.0.1

______________________________________________________________________

### initialize(...)

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

Initialize the Google Mobile Ads SDK.

Must be called once before loading any ads, after the consent has been gathered with `requestConsent(...)`.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### loadAppOpenAd(...)

```
loadAppOpenAd(options: LoadAppOpenAdOptions) => Promise<LoadAppOpenAdResult>
```

Load an app open ad.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `LoadAppOpenAdOptions` |

**Returns:** `Promise<LoadAppOpenAdResult>`

**Since:** 0.0.1

______________________________________________________________________

### loadInterstitialAd(...)

```
loadInterstitialAd(options: LoadInterstitialAdOptions) => Promise<LoadInterstitialAdResult>
```

Load an interstitial ad.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `LoadInterstitialAdOptions` |

**Returns:** `Promise<LoadInterstitialAdResult>`

**Since:** 0.0.1

______________________________________________________________________

### loadRewardedAd(...)

```
loadRewardedAd(options: LoadRewardedAdOptions) => Promise<LoadRewardedAdResult>
```

Load a rewarded ad.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `LoadRewardedAdOptions` |

**Returns:** `Promise<LoadRewardedAdResult>`

**Since:** 0.0.1

______________________________________________________________________

### loadRewardedInterstitialAd(...)

```
loadRewardedInterstitialAd(options: LoadRewardedInterstitialAdOptions) => Promise<LoadRewardedInterstitialAdResult>
```

Load a rewarded interstitial ad.

Only available on Android and iOS.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `LoadRewardedInterstitialAdOptions` |

**Returns:** `Promise<LoadRewardedInterstitialAdResult>`

**Since:** 0.0.1

______________________________________________________________________

### removeBanner(...)

```
removeBanner(options: RemoveBannerOptions) => Promise<void>
```

Remove and destroy a banner ad.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `RemoveBannerOptions` |

**Since:** 0.0.1

______________________________________________________________________

### requestConsent(...)

```
requestConsent(options?: RequestConsentOptions | undefined) => Promise<RequestConsentResult>
```

Request the latest consent information from the User Messaging Platform (UMP) and show the consent form if consent is required.

Call this method on every app launch before initializing the Google Mobile Ads SDK.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `RequestConsentOptions` |

**Returns:** `Promise<RequestConsentResult>`

**Since:** 0.0.1

______________________________________________________________________

### resetConsent()

```
resetConsent() => Promise<void>
```

Reset the consent state of the User Messaging Platform (UMP).

This method should only be used for testing purposes.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### resumeBanner(...)

```
resumeBanner(options: ResumeBannerOptions) => Promise<void>
```

Show a hidden banner ad again.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ResumeBannerOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setApplicationMuted(...)

```
setApplicationMuted(options: SetApplicationMutedOptions) => Promise<void>
```

Set whether the app is muted for ad playback.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `SetApplicationMutedOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setApplicationVolume(...)

```
setApplicationVolume(options: SetApplicationVolumeOptions) => Promise<void>
```

Set the app volume for ad playback.

Only available on Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `SetApplicationVolumeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setBannerFrame(...)

```
setBannerFrame(options: SetBannerFrameOptions) => Promise<void>
```

Update the frame of a banner ad that was shown with a frame, for example after a layout change.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SetBannerFrameOptions` |

**Since:** 0.0.1

______________________________________________________________________

### showAppOpenAd(...)

```
showAppOpenAd(options: ShowAppOpenAdOptions) => Promise<void>
```

Show a loaded app open ad.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `ShowAppOpenAdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### showBanner(...)

```
showBanner(options: ShowBannerOptions) => Promise<ShowBannerResult>
```

Load and show a banner ad.

Multiple banner ads can be shown at the same time by using different identifiers.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `ShowBannerOptions` |

**Returns:** `Promise<ShowBannerResult>`

**Since:** 0.0.1

______________________________________________________________________

### showInterstitialAd(...)

```
showInterstitialAd(options: ShowInterstitialAdOptions) => Promise<void>
```

Show a loaded interstitial ad.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `ShowInterstitialAdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### showPrivacyOptionsForm()

```
showPrivacyOptionsForm() => Promise<void>
```

Show the privacy options form of the User Messaging Platform (UMP).

Call this method when the user wants to change the consent settings, for example from a privacy settings page. Only required if `privacyOptionsRequired` is `true` in the result of `requestConsent(...)`.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### showRewardedAd(...)

```
showRewardedAd(options: ShowRewardedAdOptions) => Promise<void>
```

Show a loaded rewarded ad.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `ShowRewardedAdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### showRewardedInterstitialAd(...)

```
showRewardedInterstitialAd(options: ShowRewardedInterstitialAdOptions) => Promise<void>
```

Show a loaded rewarded interstitial ad.

Only available on Android and iOS.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `ShowRewardedInterstitialAdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('adClicked', ...)

```
addListener(eventName: 'adClicked', listenerFunc: (event: AdClickedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has been clicked.

Only available on Android and iOS.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'adClicked'`                     |
| **`listenerFunc`** | `(event: AdClickedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adDismissed', ...)

```
addListener(eventName: 'adDismissed', listenerFunc: (event: AdDismissedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a full-screen ad has been dismissed.

Only available on Android and iOS.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'adDismissed'`                     |
| **`listenerFunc`** | `(event: AdDismissedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adFailedToLoad', ...)

```
addListener(eventName: 'adFailedToLoad', listenerFunc: (event: AdFailedToLoadEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has failed to load.

Only available on Android and iOS.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'adFailedToLoad'`                     |
| **`listenerFunc`** | `(event: AdFailedToLoadEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adFailedToShow', ...)

```
addListener(eventName: 'adFailedToShow', listenerFunc: (event: AdFailedToShowEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has failed to show.

Only available on Android and iOS.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'adFailedToShow'`                     |
| **`listenerFunc`** | `(event: AdFailedToShowEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adImpressionRecorded', ...)

```
addListener(eventName: 'adImpressionRecorded', listenerFunc: (event: AdImpressionRecordedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has recorded an impression.

Only available on Android and iOS.

| Param              | Type                                         |
| ------------------ | -------------------------------------------- |
| **`eventName`**    | `'adImpressionRecorded'`                     |
| **`listenerFunc`** | `(event: AdImpressionRecordedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adLoaded', ...)

```
addListener(eventName: 'adLoaded', listenerFunc: (event: AdLoadedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has been loaded.

Only available on Android and iOS.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'adLoaded'`                     |
| **`listenerFunc`** | `(event: AdLoadedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adRevenuePaid', ...)

```
addListener(eventName: 'adRevenuePaid', listenerFunc: (event: AdRevenuePaidEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has earned revenue.

Use this event to track the ad revenue of your app, for example for lifetime value (LTV) pipelines.

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'adRevenuePaid'`                     |
| **`listenerFunc`** | `(event: AdRevenuePaidEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('adShowed', ...)

```
addListener(eventName: 'adShowed', listenerFunc: (event: AdShowedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an ad has been shown.

Only available on Android and iOS.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'adShowed'`                     |
| **`listenerFunc`** | `(event: AdShowedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('bannerSizeChanged', ...)

```
addListener(eventName: 'bannerSizeChanged', listenerFunc: (event: BannerSizeChangedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the size of a banner ad has changed, for example after a collapsible banner has been expanded or collapsed.

Only available on Android and iOS.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'bannerSizeChanged'`                     |
| **`listenerFunc`** | `(event: BannerSizeChangedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('rewardEarned', ...)

```
addListener(eventName: 'rewardEarned', listenerFunc: (event: RewardEarnedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user has earned a reward from a rewarded ad or a rewarded interstitial ad.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'rewardEarned'`                     |
| **`listenerFunc`** | `(event: RewardEarnedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### EnableAppOpenAutoShowOptions

| Prop              | Type     | Description                                                                   | Default | Since |
| ----------------- | -------- | ----------------------------------------------------------------------------- | ------- | ----- |
| **`adUnitId`**    | `string` | The ad unit ID of the app open ad.                                            |         | 0.0.1 |
| **`minInterval`** | `number` | The minimum interval in seconds between two automatically shown app open ads. | `14400` | 0.0.1 |

#### HideBannerOptions

| Prop     | Type     | Description                              | Since |
| -------- | -------- | ---------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the banner ad to hide. | 0.0.1 |

#### InitializeOptions

| Prop                               | Type                 | Description                                                                                                               | Since |
| ---------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`maxAdContentRating`**           | `MaxAdContentRating` | The maximum ad content rating for all ad requests.                                                                        | 0.0.1 |
| **`tagForChildDirectedTreatment`** | `boolean`            | Whether the app should be treated as child-directed for purposes of the Children's Online Privacy Protection Act (COPPA). | 0.0.1 |
| **`tagForUnderAgeOfConsent`**      | `boolean`            | Whether the ad requests should be handled in a manner suitable for users under the age of consent.                        | 0.0.1 |
| **`testDeviceIds`**                | `string[]`           | The identifiers of the devices that should receive test ads.                                                              | 0.0.1 |

#### LoadAppOpenAdResult

| Prop     | Type     | Description               | Since |
| -------- | -------- | ------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad. | 0.0.1 |

#### LoadAppOpenAdOptions

| Prop                 | Type               | Description                                                                  | Since |
| -------------------- | ------------------ | ---------------------------------------------------------------------------- | ----- |
| **`adUnitId`**       | `string`           | The ad unit ID of the app open ad.                                           | 0.0.1 |
| **`id`**             | `string`           | The identifier of the ad. If not provided, a random identifier is generated. | 0.0.1 |
| **`requestOptions`** | `AdRequestOptions` | The additional options for the ad request.                                   | 0.0.1 |

#### AdRequestOptions

| Prop             | Type       | Description                                                                                                                                           | Since |
| ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`contentUrl`** | `string`   | The URL string for a web page whose content matches the app's primary content. This web page content is used for targeting and brand safety purposes. | 0.0.1 |
| **`keywords`**   | `string[]` | The keywords describing the app's content for targeting purposes.                                                                                     | 0.0.1 |

#### LoadInterstitialAdResult

| Prop     | Type     | Description               | Since |
| -------- | -------- | ------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad. | 0.0.1 |

#### LoadInterstitialAdOptions

| Prop                 | Type               | Description                                                                  | Since |
| -------------------- | ------------------ | ---------------------------------------------------------------------------- | ----- |
| **`adUnitId`**       | `string`           | The ad unit ID of the interstitial ad.                                       | 0.0.1 |
| **`id`**             | `string`           | The identifier of the ad. If not provided, a random identifier is generated. | 0.0.1 |
| **`requestOptions`** | `AdRequestOptions` | The additional options for the ad request.                                   | 0.0.1 |

#### LoadRewardedAdResult

| Prop     | Type     | Description               | Since |
| -------- | -------- | ------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad. | 0.0.1 |

#### LoadRewardedAdOptions

| Prop                         | Type                            | Description                                                                  | Since |
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------- | ----- |
| **`adUnitId`**               | `string`                        | The ad unit ID of the rewarded ad.                                           | 0.0.1 |
| **`id`**                     | `string`                        | The identifier of the ad. If not provided, a random identifier is generated. | 0.0.1 |
| **`requestOptions`**         | `AdRequestOptions`              | The additional options for the ad request.                                   | 0.0.1 |
| **`serverSideVerification`** | `ServerSideVerificationOptions` | The options for the server-side verification (SSV) of reward grants.         | 0.0.1 |

#### ServerSideVerificationOptions

| Prop             | Type     | Description                                                              | Since |
| ---------------- | -------- | ------------------------------------------------------------------------ | ----- |
| **`customData`** | `string` | The custom data to include in the server-side verification callback.     | 0.0.1 |
| **`userId`**     | `string` | The user identifier to include in the server-side verification callback. | 0.0.1 |

#### LoadRewardedInterstitialAdResult

| Prop     | Type     | Description               | Since |
| -------- | -------- | ------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad. | 0.0.1 |

#### LoadRewardedInterstitialAdOptions

| Prop                         | Type                            | Description                                                                  | Since |
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------- | ----- |
| **`adUnitId`**               | `string`                        | The ad unit ID of the rewarded interstitial ad.                              | 0.0.1 |
| **`id`**                     | `string`                        | The identifier of the ad. If not provided, a random identifier is generated. | 0.0.1 |
| **`requestOptions`**         | `AdRequestOptions`              | The additional options for the ad request.                                   | 0.0.1 |
| **`serverSideVerification`** | `ServerSideVerificationOptions` | The options for the server-side verification (SSV) of reward grants.         | 0.0.1 |

#### RemoveBannerOptions

| Prop     | Type     | Description                                | Since |
| -------- | -------- | ------------------------------------------ | ----- |
| **`id`** | `string` | The identifier of the banner ad to remove. | 0.0.1 |

#### RequestConsentResult

| Prop                         | Type            | Description                                                                                             | Since |
| ---------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- | ----- |
| **`canRequestAds`**          | `boolean`       | Whether ads can be requested.                                                                           | 0.0.1 |
| **`privacyOptionsRequired`** | `boolean`       | Whether a privacy options form should be offered to the user, for example from a privacy settings page. | 0.0.1 |
| **`status`**                 | `ConsentStatus` | The consent status.                                                                                     | 0.0.1 |

#### RequestConsentOptions

| Prop                 | Type             | Description                                                         | Since |
| -------------------- | ---------------- | ------------------------------------------------------------------- | ----- |
| **`debugGeography`** | `DebugGeography` | The debug geography for testing purposes.                           | 0.0.1 |
| **`testDeviceIds`**  | `string[]`       | The identifiers of the devices that should use the debug geography. | 0.0.1 |

#### ResumeBannerOptions

| Prop     | Type     | Description                                | Since |
| -------- | -------- | ------------------------------------------ | ----- |
| **`id`** | `string` | The identifier of the banner ad to resume. | 0.0.1 |

#### SetApplicationMutedOptions

| Prop        | Type      | Description                               | Since |
| ----------- | --------- | ----------------------------------------- | ----- |
| **`muted`** | `boolean` | Whether the app is muted for ad playback. | 0.0.1 |

#### SetApplicationVolumeOptions

| Prop         | Type     | Description                                                                                     | Since |
| ------------ | -------- | ----------------------------------------------------------------------------------------------- | ----- |
| **`volume`** | `number` | The app volume for ad playback as a value between `0` (silent) and `1` (current device volume). | 0.0.1 |

#### SetBannerFrameOptions

| Prop        | Type          | Description                      | Since |
| ----------- | ------------- | -------------------------------- | ----- |
| **`frame`** | `BannerFrame` | The new frame of the banner ad.  | 0.0.1 |
| **`id`**    | `string`      | The identifier of the banner ad. | 0.0.1 |

#### BannerFrame

The frame of a banner ad in CSS pixels, relative to the top-left corner of the web view.

| Prop         | Type     | Description                                                                                                                                                                                                | Since |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the frame in CSS pixels. Used as the maximum height for the inline adaptive banner size. Ignored for the adaptive banner size because its height is determined by the Google Mobile Ads SDK. | 0.0.1 |
| **`width`**  | `number` | The width of the frame in CSS pixels.                                                                                                                                                                      | 0.0.1 |
| **`x`**      | `number` | The x-coordinate of the frame in CSS pixels.                                                                                                                                                               | 0.0.1 |
| **`y`**      | `number` | The y-coordinate of the frame in CSS pixels.                                                                                                                                                               | 0.0.1 |

#### ShowAppOpenAdOptions

| Prop     | Type     | Description                       | Since |
| -------- | -------- | --------------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad to show. | 0.0.1 |

#### ShowBannerResult

| Prop     | Type     | Description                      | Since |
| -------- | -------- | -------------------------------- | ----- |
| **`id`** | `string` | The identifier of the banner ad. | 0.0.1 |

#### ShowBannerOptions

| Prop                 | Type               | Description                                                                                                                                                                                                                                 | Default                     | Since |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----- |
| **`adUnitId`**       | `string`           | The ad unit ID of the banner ad.                                                                                                                                                                                                            |                             | 0.0.1 |
| **`collapsible`**    | `boolean`          | Whether the banner ad is collapsible.                                                                                                                                                                                                       | `false`                     | 0.0.1 |
| **`frame`**          | `BannerFrame`      | The frame of the banner ad in CSS pixels for inline placement, for example measured with `getBoundingClientRect()`. If provided, the banner ad is placed at the given frame instead of the given position.                                  |                             | 0.0.1 |
| **`id`**             | `string`           | The identifier of the banner ad. If not provided, a random identifier is generated.                                                                                                                                                         |                             | 0.0.1 |
| **`mode`**           | `BannerMode`       | The layout mode of the banner ad. In `'overlay'` mode, the banner ad is displayed on top of the web view. In `'resize'` mode, the web view is resized so that the banner ad never overlaps the web content. Ignored if a frame is provided. | `'overlay'`                 | 0.0.1 |
| **`position`**       | `BannerPosition`   | The position of the banner ad. Ignored if a frame is provided.                                                                                                                                                                              | `'bottom'`                  | 0.0.1 |
| **`requestOptions`** | `AdRequestOptions` | The additional options for the ad request.                                                                                                                                                                                                  |                             | 0.0.1 |
| **`size`**           | `BannerSize`       | The size of the banner ad.                                                                                                                                                                                                                  | `BannerSize.AdaptiveBanner` | 0.0.1 |

#### ShowInterstitialAdOptions

| Prop     | Type     | Description                       | Since |
| -------- | -------- | --------------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad to show. | 0.0.1 |

#### ShowRewardedAdOptions

| Prop     | Type     | Description                       | Since |
| -------- | -------- | --------------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad to show. | 0.0.1 |

#### ShowRewardedInterstitialAdOptions

| Prop     | Type     | Description                       | Since |
| -------- | -------- | --------------------------------- | ----- |
| **`id`** | `string` | The identifier of the ad to show. | 0.0.1 |

#### PluginListenerHandle

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

#### AdClickedEvent

| Prop         | Type       | Description               | Since |
| ------------ | ---------- | ------------------------- | ----- |
| **`format`** | `AdFormat` | The format of the ad.     | 0.0.1 |
| **`id`**     | `string`   | The identifier of the ad. | 0.0.1 |

#### AdDismissedEvent

| Prop         | Type       | Description               | Since |
| ------------ | ---------- | ------------------------- | ----- |
| **`format`** | `AdFormat` | The format of the ad.     | 0.0.1 |
| **`id`**     | `string`   | The identifier of the ad. | 0.0.1 |

#### AdFailedToLoadEvent

| Prop               | Type       | Description                                              | Since |
| ------------------ | ---------- | -------------------------------------------------------- | ----- |
| **`errorCode`**    | `string`   | The error code reported by the Google Mobile Ads SDK.    | 0.0.1 |
| **`errorMessage`** | `string`   | The error message reported by the Google Mobile Ads SDK. | 0.0.1 |
| **`format`**       | `AdFormat` | The format of the ad.                                    | 0.0.1 |
| **`id`**           | `string`   | The identifier of the ad.                                | 0.0.1 |

#### AdFailedToShowEvent

| Prop               | Type       | Description                                              | Since |
| ------------------ | ---------- | -------------------------------------------------------- | ----- |
| **`errorCode`**    | `string`   | The error code reported by the Google Mobile Ads SDK.    | 0.0.1 |
| **`errorMessage`** | `string`   | The error message reported by the Google Mobile Ads SDK. | 0.0.1 |
| **`format`**       | `AdFormat` | The format of the ad.                                    | 0.0.1 |
| **`id`**           | `string`   | The identifier of the ad.                                | 0.0.1 |

#### AdImpressionRecordedEvent

| Prop         | Type       | Description               | Since |
| ------------ | ---------- | ------------------------- | ----- |
| **`format`** | `AdFormat` | The format of the ad.     | 0.0.1 |
| **`id`**     | `string`   | The identifier of the ad. | 0.0.1 |

#### AdLoadedEvent

| Prop         | Type       | Description               | Since |
| ------------ | ---------- | ------------------------- | ----- |
| **`format`** | `AdFormat` | The format of the ad.     | 0.0.1 |
| **`id`**     | `string`   | The identifier of the ad. | 0.0.1 |

#### AdRevenuePaidEvent

| Prop               | Type               | Description                                                          | Since |
| ------------------ | ------------------ | -------------------------------------------------------------------- | ----- |
| **`currencyCode`** | `string`           | The ISO 4217 currency code of the value.                             | 0.0.1 |
| **`format`**       | `AdFormat`         | The format of the ad.                                                | 0.0.1 |
| **`id`**           | `string`           | The identifier of the ad.                                            | 0.0.1 |
| **`precision`**    | `RevenuePrecision` | The precision of the reported value.                                 | 0.0.1 |
| **`value`**        | `number`           | The monetary value earned by the ad in the currency's standard unit. | 0.0.1 |

#### AdShowedEvent

| Prop         | Type       | Description               | Since |
| ------------ | ---------- | ------------------------- | ----- |
| **`format`** | `AdFormat` | The format of the ad.     | 0.0.1 |
| **`id`**     | `string`   | The identifier of the ad. | 0.0.1 |

#### BannerSizeChangedEvent

| Prop         | Type     | Description                                | Since |
| ------------ | -------- | ------------------------------------------ | ----- |
| **`height`** | `number` | The height of the banner ad in CSS pixels. | 0.0.1 |
| **`id`**     | `string` | The identifier of the banner ad.           | 0.0.1 |
| **`width`**  | `number` | The width of the banner ad in CSS pixels.  | 0.0.1 |

#### RewardEarnedEvent

| Prop         | Type     | Description               | Since |
| ------------ | -------- | ------------------------- | ----- |
| **`amount`** | `number` | The amount of the reward. | 0.0.1 |
| **`id`**     | `string` | The identifier of the ad. | 0.0.1 |
| **`type`**   | `string` | The type of the reward.   | 0.0.1 |

### Type Aliases

#### ConsentStatus

The consent status of the User Messaging Platform (UMP).

`'not-required' | 'obtained' | 'required' | 'unknown'`

#### BannerMode

The layout mode of a banner ad.

`'overlay' | 'resize'`

#### BannerPosition

The position of a banner ad.

`'bottom' | 'top'`

### Enums

#### MaxAdContentRating

| Members  | Value  | Description                                                 | Since |
| -------- | ------ | ----------------------------------------------------------- | ----- |
| **`G`**  | `'G'`  | Content suitable for general audiences.                     | 0.0.1 |
| **`Ma`** | `'MA'` | Content suitable only for mature audiences.                 | 0.0.1 |
| **`Pg`** | `'PG'` | Content suitable for most audiences with parental guidance. | 0.0.1 |
| **`T`**  | `'T'`  | Content suitable for teen and older audiences.              | 0.0.1 |

#### DebugGeography

| Members                | Value                  | Description                                                            | Since |
| ---------------------- | ---------------------- | ---------------------------------------------------------------------- | ----- |
| **`Disabled`**         | `'DISABLED'`           | The debug geography is disabled.                                       | 0.0.1 |
| **`Eea`**              | `'EEA'`                | The device appears as located in the European Economic Area (EEA).     | 0.0.1 |
| **`Other`**            | `'OTHER'`              | The device appears as located in a region with no regulation in force. | 0.0.1 |
| **`RegulatedUsState`** | `'REGULATED_US_STATE'` | The device appears as located in a regulated US state.                 | 0.0.1 |

#### BannerSize

| Members                    | Value                      | Description                                                                                                                                                             | Since |
| -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`AdaptiveBanner`**       | `'ADAPTIVE_BANNER'`        | An adaptive banner with a width that matches the screen width (or the frame width if a frame is provided) and a height that is determined by the Google Mobile Ads SDK. | 0.0.1 |
| **`Banner`**               | `'BANNER'`                 | A standard banner with a size of 320x50.                                                                                                                                | 0.0.1 |
| **`FullBanner`**           | `'FULL_BANNER'`            | A full-size banner with a size of 468x60 (tablets only).                                                                                                                | 0.0.1 |
| **`InlineAdaptiveBanner`** | `'INLINE_ADAPTIVE_BANNER'` | An adaptive banner for inline placement in scrolling content with a height that is limited by the height of the provided frame.                                         | 0.0.1 |
| **`LargeBanner`**          | `'LARGE_BANNER'`           | A large banner with a size of 320x100.                                                                                                                                  | 0.0.1 |
| **`Leaderboard`**          | `'LEADERBOARD'`            | A leaderboard banner with a size of 728x90 (tablets only).                                                                                                              | 0.0.1 |
| **`MediumRectangle`**      | `'MEDIUM_RECTANGLE'`       | A medium rectangle banner with a size of 300x250.                                                                                                                       | 0.0.1 |

#### AdFormat

| Members                    | Value                     | Description                 | Since |
| -------------------------- | ------------------------- | --------------------------- | ----- |
| **`AppOpen`**              | `'APP_OPEN'`              | An app open ad.             | 0.0.1 |
| **`Banner`**               | `'BANNER'`                | A banner ad.                | 0.0.1 |
| **`Interstitial`**         | `'INTERSTITIAL'`          | An interstitial ad.         | 0.0.1 |
| **`Rewarded`**             | `'REWARDED'`              | A rewarded ad.              | 0.0.1 |
| **`RewardedInterstitial`** | `'REWARDED_INTERSTITIAL'` | A rewarded interstitial ad. | 0.0.1 |

#### RevenuePrecision

| Members                 | Value                  | Description                                     | Since |
| ----------------------- | ---------------------- | ----------------------------------------------- | ----- |
| **`Estimated`**         | `'ESTIMATED'`          | The value is estimated.                         | 0.0.1 |
| **`Precise`**           | `'PRECISE'`            | The value is the precise value paid for the ad. | 0.0.1 |
| **`PublisherProvided`** | `'PUBLISHER_PROVIDED'` | The value is provided by the publisher.         | 0.0.1 |
| **`Unknown`**           | `'UNKNOWN'`            | The value is unknown.                           | 0.0.1 |

## FAQ

### How is this plugin different from other similar plugins?

It covers the full AdMob surface on Android and iOS — banner, interstitial, rewarded, rewarded interstitial and app open ads — built on the Next-Gen Google Mobile Ads SDK, with correct edge-to-edge banner layout, ad revenue events for your LTV pipelines, and the canonical User Messaging Platform (UMP) consent flow in a single method call. Every ad format shares a uniform load/show API, rejections carry typed error codes, and you can run multiple typed ad instances at once — all fully typed, actively maintained against the latest SDK and Capacitor versions, and backed by dedicated support. If you only need a single banner, a minimal integration may be enough; if you want the complete monetization and consent story in one dependency, this plugin is built for it.

### Are ads available on the web?

No. AdMob is a mobile advertising product, so all methods are only available on Android and iOS. On the web, all methods reject with an unimplemented error. For web advertising, take a look at [Google AdSense](https://adsense.google.com/).

### Why do my ad requests fail with `CONSENT_NOT_GATHERED`?

The plugin only requests ads if the consent requirements are met. Call `requestConsent(...)` on every app launch before loading any ads. See [Usage](#gather-consent-and-initialize-the-sdk) for the canonical flow.

### Why does my app crash on Android without this plugin's error message?

The Google Mobile Ads SDK crashes the app if the AdMob app ID is missing or invalid. The plugin detects a missing app ID and rejects `initialize(...)` with a clear error message instead. However, it cannot detect an *invalid* app ID, so double-check the value in your `AndroidManifest.xml` and `Info.plist` files.

### Do I have to comply with any ad policies?

Yes. Apps that show AdMob ads must comply with [Google's ad policies](https://support.google.com/admob/answer/6128543) and, in the EEA and the UK, with Google's [EU User Consent Policy](https://www.google.com/about/company/user-consent-policy/). This plugin ships the User Messaging Platform (UMP) consent flow to help you with that (see [Usage](#gather-consent-and-initialize-the-sdk)).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/): Ask happy users for a review at the right moment.
- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the tracking permission on iOS for personalized ads.
- [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/): Offer an ad-free experience with in-app purchases.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/admob/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/admob/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/admob/LICENSE).

# Capacitor Age Signals Plugin

Capacitor plugin to use the [Play Age Signals API](https://developer.android.com/google/play/age-signals/overview) (Android) and [DeclaredAgeRange](https://developer.apple.com/documentation/declaredagerange/) (iOS) to request age signals about the user.

## Features

The Capacitor Age Signals plugin is one of the most complete age assurance solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🔍 **Age Verification**: Request user age signals using Play Age Signals API (Android) and DeclaredAgeRange (iOS).
- 👨‍👩‍👧‍👦 **Parental Controls**: Support for supervised accounts with parental approval status.
- 🧪 **Testing Support**: Built-in `FakeAgeSignalsManager` integration for testing different age verification scenarios (Android).
- 🌍 **Compliance Ready**: Built for US state age verification requirements (effective January 1, 2026).
- 🤝 **Compatibility**: Works alongside the [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/) and [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Age Signals plugin is typically used to comply with age verification requirements and to tailor the app experience to the user's age, for example:

- **Age-gated content**: Restrict access to mature or sensitive content based on the user's verification status and age range.
- **Regulatory compliance**: Meet US state age verification requirements by requesting age signals from Google Play and Apple's DeclaredAgeRange API.
- **Parental supervision**: Detect supervised accounts and react to pending or denied parental approvals.
- **Regional eligibility checks**: Use `getRegulatoryRequirements()` on iOS to determine whether the user is in a region with additional age-related obligations.
- **Automated testing**: Simulate different age verification scenarios in your Android tests using the built-in fake manager.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.3.x          | >=8.x.x           | Active support |
| 0.2.x          | 7.x.x             | Deprecated     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-age-signals` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-age-signals
npx cap sync
```

### Android

#### 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:

- `$androidPlayAgeSignalsVersion` version of `com.google.android.play:age-signals` (default: `0.0.4`)

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

**Note**: The `FakeAgeSignalsManager` testing API is included in the main `age-signals` library, so no additional dependency is required for testing.

### iOS

#### Entitlements

To use the DeclaredAgeRange API, you must enable the `com.apple.developer.declared-age-range` entitlement in your app's entitlements file by adding the following key:

```
<key>com.apple.developer.declared-age-range</key>
<true/>
```

Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.contacts.notes) for more information.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to request the user's age range and how to react to the regulatory requirements that apply to the user.

### Request the user's age range

Call `requestAgeRange(...)` to ask the user to share their age range. The status tells you whether the age range was shared, and the `ageRange` property contains the bounds:

```
import { AgeRangeStatus, AgeSignals } from '@capawesome/capacitor-age-signals';

const requestAgeRange = async () => {
  const result = await AgeSignals.requestAgeRange();
  if (result.status !== AgeRangeStatus.Shared) {
    console.log('The user has not shared their age range:', result.status);
    return;
  }
  console.log('Lower Bound:', result.ageRange?.lowerBound);
  console.log('Upper Bound:', result.ageRange?.upperBound);
};
```

On Android, a status of `VERIFICATION_REQUIRED` means the user must resolve their status in the Google Play Store before an age range can be shared.

### Read the age range without prompting

Call `getAgeRange()` to read the age range again without showing a prompt. This is useful to poll for a `significantChange` status that moves from `PENDING` to `APPROVED`. Only available on Android:

```
import { AgeSignals } from '@capawesome/capacitor-age-signals';

const getAgeRange = async () => {
  const result = await AgeSignals.getAgeRange();
  console.log('Significant Change:', result.significantChange?.status);
};
```

### Check the regulatory requirements

Check whether the user is in a region and account state that requires age assurance, and which regulatory features your app must support. Only available on iOS:

```
import {
  AgeSignals,
  RegulatoryFeature,
} from '@capawesome/capacitor-age-signals';

const getRegulatoryRequirements = async () => {
  const result = await AgeSignals.getRegulatoryRequirements();
  if (
    result.regulatoryFeatures.includes(
      RegulatoryFeature.SignificantAppChangeRequiresAdultNotification,
    )
  ) {
    await AgeSignals.showSignificantUpdateAcknowledgment({
      updateDescription: 'This app now supports direct messages between users.',
    });
  }
};
```

## API

- [`getAgeRange()`](#getagerange)
- [`getRegulatoryRequirements()`](#getregulatoryrequirements)
- [`isAvailable()`](#isavailable)
- [`requestAgeRange(...)`](#requestagerange)
- [`setNextAgeSignalsAccessResult(...)`](#setnextagesignalsaccessresult)
- [`setNextAgeSignalsException(...)`](#setnextagesignalsexception)
- [`setNextAgeSignalsResult(...)`](#setnextagesignalsresult)
- [`setNextRequestAgeSignalsAccessException(...)`](#setnextrequestagesignalsaccessexception)
- [`setUseFakeManager(...)`](#setusefakemanager)
- [`showSignificantUpdateAcknowledgment(...)`](#showsignificantupdateacknowledgment)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getAgeRange()

```
getAgeRange() => Promise<GetAgeRangeResult>
```

Get the age range that the user has already shared with the app.

This method never shows a system prompt. Call `requestAgeRange(...)` first and only call this method if the returned status was `SHARED`.

Use this method to poll for changes (for example a `significantChange` status that moves from `PENDING` to `APPROVED`) without prompting the user again.

Only available on Android.

**Returns:** `Promise<GetAgeRangeResult>`

**Since:** 0.5.0

______________________________________________________________________

### getRegulatoryRequirements()

```
getRegulatoryRequirements() => Promise<GetRegulatoryRequirementsResult>
```

Get the regulatory requirements that apply to the current user.

Call this method before starting any age assurance flow to find out whether the user is in a region and account state where age assurance applies at all.

Only available on iOS (26.2+).

**Returns:** `Promise<GetRegulatoryRequirementsResult>`

**Since:** 0.5.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether age signals are available on this device.

On **Android**, this checks whether the Google Play Store is installed. On **iOS**, this checks whether the device runs iOS 26.0 or later.

A result of `true` does not guarantee that an age range can be retrieved. Always handle the errors of the other methods as well.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.5.0

______________________________________________________________________

### requestAgeRange(...)

```
requestAgeRange(options?: RequestAgeRangeOptions | undefined) => Promise<RequestAgeRangeResult>
```

Ask the user to share their age range with the app.

This method may show a system prompt. The system caches the decision of the user, so subsequent calls may resolve without any user interaction.

On **Android**, the prompt is only shown to unsupervised users who have chosen to be asked before sharing. It is not shown in regions where age verification is mandatory. In that case the status is `VERIFICATION_REQUIRED` and the user must resolve their status in the Google Play Store. Google Play also suppresses the prompt after the user has dismissed or declined it a few times. On **iOS**, the prompt is not shown in regions where age assurance is mandatory. In that case the age range is shared without user interaction.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `RequestAgeRangeOptions` |

**Returns:** `Promise<RequestAgeRangeResult>`

**Since:** 0.5.0

______________________________________________________________________

### setNextAgeSignalsAccessResult(...)

```
setNextAgeSignalsAccessResult(options: SetNextAgeSignalsAccessResultOptions) => Promise<void>
```

Set the next access result to be returned by the fake manager.

Only available on Android.

| Param         | Type                                   |
| ------------- | -------------------------------------- |
| **`options`** | `SetNextAgeSignalsAccessResultOptions` |

**Since:** 0.5.0

______________________________________________________________________

### setNextAgeSignalsException(...)

```
setNextAgeSignalsException(options: SetNextAgeSignalsExceptionOptions) => Promise<void>
```

Set the next error to be thrown by the fake manager when the age range is read.

Only available on Android.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `SetNextAgeSignalsExceptionOptions` |

**Since:** 0.3.1

______________________________________________________________________

### setNextAgeSignalsResult(...)

```
setNextAgeSignalsResult(options: SetNextAgeSignalsResultOptions) => Promise<void>
```

Set the next age range result to be returned by the fake manager.

Only available on Android.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SetNextAgeSignalsResultOptions` |

**Since:** 0.3.1

______________________________________________________________________

### setNextRequestAgeSignalsAccessException(...)

```
setNextRequestAgeSignalsAccessException(options: SetNextRequestAgeSignalsAccessExceptionOptions) => Promise<void>
```

Set the next error to be thrown by the fake manager when access to the age range is requested.

Only available on Android.

| Param         | Type                                             |
| ------------- | ------------------------------------------------ |
| **`options`** | `SetNextRequestAgeSignalsAccessExceptionOptions` |

**Since:** 0.5.0

______________________________________________________________________

### setUseFakeManager(...)

```
setUseFakeManager(options: SetUseFakeManagerOptions) => Promise<void>
```

Enable or disable the fake manager for testing.

The fake manager is only available in debuggable builds. In release builds this method rejects with `FAKE_MANAGER_NOT_ALLOWED`, because it would otherwise allow age signals to be forged from the web layer.

Only available on Android.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `SetUseFakeManagerOptions` |

**Since:** 0.3.1

______________________________________________________________________

### showSignificantUpdateAcknowledgment(...)

```
showSignificantUpdateAcknowledgment(options: ShowSignificantUpdateAcknowledgmentOptions) => Promise<void>
```

Show a system interface that lets the user acknowledge a significant change to the app.

Only call this method if `getRegulatoryRequirements()` returned `SIGNIFICANT_APP_CHANGE_REQUIRES_ADULT_NOTIFICATION`.

Only available on iOS (26.4+).

| Param         | Type                                         |
| ------------- | -------------------------------------------- |
| **`options`** | `ShowSignificantUpdateAcknowledgmentOptions` |

**Since:** 0.5.0

______________________________________________________________________

### Interfaces

#### GetAgeRangeResult

| Prop                    | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Since |
| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ageRange`**          | `AgeRange`          | The age range that the user has shared with the app. `undefined` if the user has not shared their age range.                                                                                                                                                                                                                                                                                                     | 0.5.0 |
| **`installId`**         | `string`            | An ID assigned to supervised user installs by Google Play, used for the purposes of notifying you of revoked app approval. Only available on Android.                                                                                                                                                                                                                                                            | 0.5.0 |
| **`significantChange`** | `SignificantChange` | The parental approval state for the significant changes of the app. Significant changes are declared in the Google Play Console. Google Play then asks the parent or guardian of a supervised user to approve them. `undefined` if the user is not supervised, if no significant change has been declared yet or if significant changes do not apply in the jurisdiction of the user. Only available on Android. | 0.5.0 |

#### AgeRange

| Prop                         | Type                  | Description                                                                                                                                                                     | Since |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`activeParentalControls`** | `ParentalControl[]`   | The parental controls that are active for the user. Only available on iOS.                                                                                                      | 0.5.0 |
| **`ageRangeDeclaration`**    | `AgeRangeDeclaration` | How the age range was declared. The more granular values are only returned in some regions. `undefined` if the system does not provide this information. Only available on iOS. | 0.5.0 |
| **`ageRangeSource`**         | `AgeRangeSource`      | How the age range was established. `undefined` if the system does not provide this information. Only available on Android.                                                      | 0.5.0 |
| **`lowerBound`**             | `number`              | The (inclusive) lower bound of the age range. `undefined` if the user is below the lowest requested age gate.                                                                   | 0.5.0 |
| **`upperBound`**             | `number`              | The (inclusive) upper bound of the age range. `undefined` if the user meets or exceeds the highest requested age gate.                                                          | 0.5.0 |

#### SignificantChange

| Prop               | Type                      | Description                                                                                                                                                                                                                       | Since |
| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`approvalDate`** | `string`                  | The effective date of the most recently approved significant change, in ISO 8601 format. All significant changes with an earlier effective date are approved as well. `undefined` if no significant change has been approved yet. | 0.5.0 |
| **`status`**       | `SignificantChangeStatus` | The parental approval state for the most recent significant change.                                                                                                                                                               | 0.5.0 |

#### GetRegulatoryRequirementsResult

| Prop                       | Type                  | Description                                                                                                          | Since |
| -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ageAssuranceRequired`** | `boolean`             | Whether the user must share their age range because of a law or regulation that applies to their region and account. | 0.5.0 |
| **`regulatoryFeatures`**   | `RegulatoryFeature[]` | The regulatory features that the app must support for this user. Empty on iOS versions below 26.4.                   | 0.5.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                       | Since |
| --------------- | --------- | ------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether age signals are available on this device. | 0.5.0 |

#### RequestAgeRangeResult

| Prop                    | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Since |
| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ageRange`**          | `AgeRange`          | The age range that the user has shared with the app. `undefined` if the status is not `SHARED`.                                                                                                                                                                                                                                                                                                                  | 0.5.0 |
| **`installId`**         | `string`            | An ID assigned to supervised user installs by Google Play, used for the purposes of notifying you of revoked app approval. Only available on Android.                                                                                                                                                                                                                                                            | 0.5.0 |
| **`significantChange`** | `SignificantChange` | The parental approval state for the significant changes of the app. Significant changes are declared in the Google Play Console. Google Play then asks the parent or guardian of a supervised user to approve them. `undefined` if the user is not supervised, if no significant change has been declared yet or if significant changes do not apply in the jurisdiction of the user. Only available on Android. | 0.5.0 |
| **`status`**            | `AgeRangeStatus`    | Whether the user has shared their age range with the app.                                                                                                                                                                                                                                                                                                                                                        | 0.5.0 |

#### RequestAgeRangeOptions

| Prop           | Type       | Description                                                                                                                                                                                                                                                                                                                                          | Default        | Since |
| -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----- |
| **`ageGates`** | `number[]` | The age thresholds that are relevant for the app. The provided array must contain at least 1 and at most 3 ages. The ages must be sorted in ascending order and must be at least two years apart from each other. The system may ignore these thresholds and return a different age range if a law or regulation requires it. Only available on iOS. | `[13, 15, 18]` | 0.5.0 |

#### SetNextAgeSignalsAccessResultOptions

| Prop         | Type             | Description                                    | Since |
| ------------ | ---------------- | ---------------------------------------------- | ----- |
| **`status`** | `AgeRangeStatus` | The status to be returned by the fake manager. | 0.5.0 |

#### SetNextAgeSignalsExceptionOptions

| Prop            | Type        | Description                                                                                                        | Since |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
| **`errorCode`** | `ErrorCode` | The error code to be thrown by the fake manager. Only the error codes that are available on Android are supported. | 0.3.1 |

#### SetNextAgeSignalsResultOptions

| Prop                                | Type                      | Description                                                                              | Since |
| ----------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------- | ----- |
| **`ageLower`**                      | `number`                  | The (inclusive) lower bound of the age range.                                            | 0.3.1 |
| **`ageRangeSource`**                | `AgeRangeSource`          | How the age range was established.                                                       | 0.5.0 |
| **`ageUpper`**                      | `number`                  | The (inclusive) upper bound of the age range.                                            | 0.3.1 |
| **`installId`**                     | `string`                  | An ID assigned to supervised user installs by Google Play.                               | 0.3.1 |
| **`significantChangeApprovalDate`** | `string`                  | The effective date of the most recently approved significant change, in ISO 8601 format. | 0.5.0 |
| **`significantChangeStatus`**       | `SignificantChangeStatus` | The parental approval state for the most recent significant change.                      | 0.5.0 |

#### SetNextRequestAgeSignalsAccessExceptionOptions

| Prop            | Type        | Description                                                                                                        | Since |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
| **`errorCode`** | `ErrorCode` | The error code to be thrown by the fake manager. Only the error codes that are available on Android are supported. | 0.5.0 |

#### SetUseFakeManagerOptions

| Prop          | Type      | Description                                  | Default | Since |
| ------------- | --------- | -------------------------------------------- | ------- | ----- |
| **`useFake`** | `boolean` | Whether to use the fake manager for testing. | `false` | 0.3.1 |

#### ShowSignificantUpdateAcknowledgmentOptions

| Prop                    | Type     | Description                                                                              | Since |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------- | ----- |
| **`updateDescription`** | `string` | A short description of what has changed in the app and why the user must acknowledge it. | 0.5.0 |

### Enums

#### ParentalControl

| Members                   | Value                    | Description                                                | Since |
| ------------------------- | ------------------------ | ---------------------------------------------------------- | ----- |
| **`CommunicationLimits`** | `'COMMUNICATION_LIMITS'` | The system limits the communication features for the user. | 0.5.0 |

#### AgeRangeDeclaration

| Members                            | Value                                | Description                                                                                                           | Since |
| ---------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`CheckedByOtherMethod`**         | `'CHECKED_BY_OTHER_METHOD'`          | The user set their own age range using an unspecified method. Only available on iOS (26.2+).                          | 0.5.0 |
| **`Confirmed`**                    | `'CONFIRMED'`                        | The age range was set using a scrutinized method, like a credit card or government ID. Only available on iOS (26.5+). | 0.4.0 |
| **`GovernmentIdChecked`**          | `'GOVERNMENT_ID_CHECKED'`            | The user set their own age range using a government ID. Only available on iOS (26.2+).                                | 0.5.0 |
| **`GuardianCheckedByOtherMethod`** | `'GUARDIAN_CHECKED_BY_OTHER_METHOD'` | A parent or guardian set the age range using an unspecified method. Only available on iOS (26.2+).                    | 0.5.0 |
| **`GuardianDeclared`**             | `'GUARDIAN_DECLARED'`                | A parent or guardian declared the age range without external verification.                                            | 0.4.0 |
| **`GuardianGovernmentIdChecked`**  | `'GUARDIAN_GOVERNMENT_ID_CHECKED'`   | A parent or guardian set the age range using a government ID. Only available on iOS (26.2+).                          | 0.5.0 |
| **`GuardianPaymentChecked`**       | `'GUARDIAN_PAYMENT_CHECKED'`         | A parent or guardian set the age range using a payment method, like a credit card. Only available on iOS (26.2+).     | 0.5.0 |
| **`PaymentChecked`**               | `'PAYMENT_CHECKED'`                  | The user set their own age range using a payment method, like a credit card. Only available on iOS (26.2+).           | 0.5.0 |
| **`SelfDeclared`**                 | `'SELF_DECLARED'`                    | The user declared their own age range without external verification.                                                  | 0.4.0 |

#### AgeRangeSource

| Members     | Value      | Description                                                                                                               | Since |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`TierA`** | `'TIER_A'` | The user has self-declared their age.                                                                                     | 0.5.0 |
| **`TierB`** | `'TIER_B'` | The age of the user is managed by a parent or guardian.                                                                   | 0.5.0 |
| **`TierC`** | `'TIER_C'` | The age of the user was assessed using a credit card, an email address, a selfie assessment, a government ID or a tax ID. | 0.5.0 |
| **`TierD`** | `'TIER_D'` | The age of the user was checked using a combination of a government ID and a selfie assessment, or using a digital ID.    | 0.5.0 |

#### SignificantChangeStatus

| Members        | Value        | Description                                                                                               | Since |
| -------------- | ------------ | --------------------------------------------------------------------------------------------------------- | ----- |
| **`Approved`** | `'APPROVED'` | The parent or guardian has approved the most recent significant change and all prior significant changes. | 0.5.0 |
| **`Declined`** | `'DECLINED'` | The parent or guardian has declined one or more significant changes.                                      | 0.5.0 |
| **`Pending`**  | `'PENDING'`  | The parent or guardian has not yet approved one or more significant changes.                              | 0.5.0 |

#### RegulatoryFeature

| Members                                             | Value                                                  | Description                                                                                                                                                                        | Since |
| --------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`DeclaredAgeRangeRequired`**                      | `'DECLARED_AGE_RANGE_REQUIRED'`                        | The user must share their age range with the app.                                                                                                                                  | 0.5.0 |
| **`SignificantAppChangeRequiresAdultNotification`** | `'SIGNIFICANT_APP_CHANGE_REQUIRES_ADULT_NOTIFICATION'` | An adult user must acknowledge a significant change of the app. Use `showSignificantUpdateAcknowledgment(...)` to show the system interface for the acknowledgment.                | 0.5.0 |
| **`SignificantAppChangeRequiresParentalConsent`**   | `'SIGNIFICANT_APP_CHANGE_REQUIRES_PARENTAL_CONSENT'`   | A parent or guardian must consent to a significant change of the app. This plugin does not implement the consent flow. Use Apple's PermissionKit framework to request the consent. | 0.5.0 |

#### AgeRangeStatus

| Members                    | Value                     | Description                                                                                                                                                                               | Since |
| -------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`NotShared`**            | `'NOT_SHARED'`            | The user has not shared their age range with the app.                                                                                                                                     | 0.5.0 |
| **`Shared`**               | `'SHARED'`                | The user has shared their age range with the app.                                                                                                                                         | 0.5.0 |
| **`Unspecified`**          | `'UNSPECIFIED'`           | The system did not specify whether the user has shared their age range. Treat this value like `NOT_SHARED`. Google Play does not document when it is returned. Only available on Android. | 0.5.0 |
| **`VerificationRequired`** | `'VERIFICATION_REQUIRED'` | The user must verify their age in the Google Play Store before the age range can be shared. Only available on Android.                                                                    | 0.5.0 |

#### ErrorCode

| Members                              | Value                                | Description                                                                                                                                                                                 | Since |
| ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ApiNotAvailable`**                | `'API_NOT_AVAILABLE'`                | The age signals API is not available. On **Android**, the Play Store app version installed on the device might be old. On **iOS**, the system was unable to share the age range.            | 0.0.1 |
| **`AppNotOwned`**                    | `'APP_NOT_OWNED'`                    | The app was not installed by Google Play. Only available on Android.                                                                                                                        | 0.0.1 |
| **`CannotBindToService`**            | `'CANNOT_BIND_TO_SERVICE'`           | Binding to the service in the Play Store has failed. This can be due to having an old Play Store version installed on the device or device memory is overloaded. Only available on Android. | 0.0.1 |
| **`ClientTransientError`**           | `'CLIENT_TRANSIENT_ERROR'`           | There was a transient error in the client device. Only available on Android.                                                                                                                | 0.0.1 |
| **`FakeManagerNotAllowed`**          | `'FAKE_MANAGER_NOT_ALLOWED'`         | The fake manager is not available, because the app is not debuggable. Only available on Android.                                                                                            | 0.5.0 |
| **`FakeManagerNotEnabled`**          | `'FAKE_MANAGER_NOT_ENABLED'`         | The fake manager is not enabled. Only available on Android.                                                                                                                                 | 0.5.0 |
| **`InternalError`**                  | `'INTERNAL_ERROR'`                   | Unknown internal error. Only available on Android.                                                                                                                                          | 0.0.1 |
| **`InvalidRequest`**                 | `'INVALID_REQUEST'`                  | The request contains invalid parameters. On **iOS**, this is also returned if the requested age gates are rejected by the system.                                                           | 0.5.0 |
| **`NetworkError`**                   | `'NETWORK_ERROR'`                    | No available network is found. Only available on Android.                                                                                                                                   | 0.0.1 |
| **`NotSupported`**                   | `'NOT_SUPPORTED'`                    | Age signals are not supported on this device.                                                                                                                                               | 0.5.0 |
| **`PlayServicesNotFound`**           | `'PLAY_SERVICES_NOT_FOUND'`          | Play Services is not available or its version is too old. Only available on Android.                                                                                                        | 0.0.1 |
| **`PlayServicesVersionOutdated`**    | `'PLAY_SERVICES_VERSION_OUTDATED'`   | Play Services needs to be updated. Only available on Android.                                                                                                                               | 0.0.1 |
| **`PlayStoreNotFound`**              | `'PLAY_STORE_NOT_FOUND'`             | No Play Store app is found on the device. Only available on Android.                                                                                                                        | 0.0.1 |
| **`PlayStoreVersionOutdated`**       | `'PLAY_STORE_VERSION_OUTDATED'`      | The Play Store app needs to be updated. Only available on Android.                                                                                                                          | 0.0.1 |
| **`PresentationContextUnavailable`** | `'PRESENTATION_CONTEXT_UNAVAILABLE'` | No view controller was found to present the system interface. Only available on iOS.                                                                                                        | 0.5.0 |
| **`SdkVersionOutdated`**             | `'SDK_VERSION_OUTDATED'`             | The Age Signals SDK version is outdated. Only available on Android.                                                                                                                         | 0.4.0 |

## Testing

The plugin includes support for the `FakeAgeSignalsManager` API on Android, which allows you to simulate different age signals scenarios in your tests without requiring live responses from Google Play.

### Android Testing

**Important**: The fake manager is only available if your app is debuggable. In release builds, `setUseFakeManager(...)` rejects with `FAKE_MANAGER_NOT_ALLOWED`, because it would otherwise allow age signals to be forged from the web layer.

**Important**: Due to a known issue in versions 0.0.1 and 0.0.2 of the Age Signals API, you may encounter a `java.lang.VerifyError` when calling the builder method of `AgeSignalsResult` in unit tests. As a workaround, run your tests as Android instrumented tests within the `androidTest` source set.

#### Example: Testing a Self-Declared Adult User

```
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
} from '@capawesome/capacitor-age-signals';

// Enable the fake manager
await AgeSignals.setUseFakeManager({ useFake: true });

// The user agrees to share their age range
await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

// Set up an adult user
await AgeSignals.setNextAgeSignalsResult({
  ageLower: 18,
  ageRangeSource: AgeRangeSource.TierA,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.status); // 'SHARED'
console.log(result.ageRange?.lowerBound); // 18
```

#### Example: Testing a Supervised User (13-17 years old)

```
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
} from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

await AgeSignals.setNextAgeSignalsResult({
  ageLower: 13,
  ageUpper: 17,
  ageRangeSource: AgeRangeSource.TierB,
  installId: 'fake_install_id',
});

const result = await AgeSignals.requestAgeRange();
console.log(result.ageRange?.lowerBound); // 13
console.log(result.ageRange?.upperBound); // 17
console.log(result.installId); // 'fake_install_id'
```

#### Example: Testing Parental Approval Scenarios

```
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
  SignificantChangeStatus,
} from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

// Test pending approval
await AgeSignals.setNextAgeSignalsResult({
  ageLower: 13,
  ageUpper: 17,
  ageRangeSource: AgeRangeSource.TierB,
  significantChangeApprovalDate: '2026-02-01T00:00:00.000Z',
  significantChangeStatus: SignificantChangeStatus.Pending,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.significantChange?.status); // 'PENDING'
console.log(result.significantChange?.approvalDate); // '2026-02-01T00:00:00.000Z'
```

#### Example: Testing a User Who Must Verify Their Age

```
import { AgeRangeStatus, AgeSignals } from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.VerificationRequired,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.status); // 'VERIFICATION_REQUIRED'
console.log(result.ageRange); // undefined
```

#### Example: Testing Error Scenarios

```
import { AgeSignals, ErrorCode } from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

// Simulate a network error while access is requested
await AgeSignals.setNextRequestAgeSignalsAccessException({
  errorCode: ErrorCode.NetworkError,
});

try {
  await AgeSignals.requestAgeRange();
} catch (error) {
  console.log('Caught network error:', error);
}

// Simulate a network error while the age range is read
await AgeSignals.setNextAgeSignalsException({
  errorCode: ErrorCode.NetworkError,
});

try {
  await AgeSignals.getAgeRange();
} catch (error) {
  console.log('Caught network error:', error);
}
```

#### Disabling the Fake Manager

```
import { AgeSignals } from '@capawesome/capacitor-age-signals';

// Switch back to the production manager
await AgeSignals.setUseFakeManager({ useFake: false });

// This will now use the real Age Signals API
const result = await AgeSignals.requestAgeRange();
```

## FAQ

### Which age verification APIs does this plugin use?

On Android, the plugin uses the [Play Age Signals API](https://developer.android.com/google/play/age-signals/overview) to request age signals from Google Play. On iOS, it uses Apple's [DeclaredAgeRange](https://developer.apple.com/documentation/declaredagerange/) framework, which requires the `com.apple.developer.declared-age-range` entitlement (see [Installation](#installation)).

### What do the different statuses mean?

The `status` property tells you whether the user shared their age range. `SHARED` means an age range is available, `NOT_SHARED` means the user declined or is not in an applicable region, and `VERIFICATION_REQUIRED` (Android only) means the user must resolve their status in the Google Play Store first.

### How do the Android age range sources map to the iOS age range declarations?

Android reports how an age was established as a tier, while iOS reports a declaration method. They do not map one to one, so both values are exposed as separate properties. The following table shows the closest equivalents:

| Android  | iOS                                                                                                          |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| `TIER_A` | `SELF_DECLARED`                                                                                              |
| `TIER_B` | `GUARDIAN_DECLARED`                                                                                          |
| `TIER_C` | `PAYMENT_CHECKED`, `CHECKED_BY_OTHER_METHOD`, `GUARDIAN_PAYMENT_CHECKED`, `GUARDIAN_CHECKED_BY_OTHER_METHOD` |
| `TIER_D` | `GOVERNMENT_ID_CHECKED`, `GUARDIAN_GOVERNMENT_ID_CHECKED`                                                    |

On iOS 26.5 and later, the more granular declarations may be replaced by `CONFIRMED`, which covers both `TIER_C` and `TIER_D`.

### How can I test different age verification scenarios?

On Android, the plugin integrates the `FakeAgeSignalsManager` API, which lets you simulate age signals without live responses from Google Play. Enable it with `setUseFakeManager(...)` and set the next results or exceptions with `setNextAgeSignalsAccessResult(...)`, `setNextAgeSignalsResult(...)`, `setNextRequestAgeSignalsAccessException(...)` and `setNextAgeSignalsException(...)`. The fake manager is only available if your app is debuggable. See the [Testing](#testing) section for complete examples.

### Why do I get a VerifyError in my Android unit tests?

Due to a known issue in versions 0.0.1 and 0.0.2 of the Age Signals API, calling the builder method of `AgeSignalsResult` in unit tests may throw a `java.lang.VerifyError`. As a workaround, run your tests as Android instrumented tests within the `androidTest` source set.

### Why does the plugin reject with an error like API_NOT_AVAILABLE or APP_NOT_OWNED?

The Play Age Signals API requires an up-to-date Play Store app and Play Services on the device, so errors like `API_NOT_AVAILABLE`, `PLAY_STORE_VERSION_OUTDATED`, or `PLAY_SERVICES_NOT_FOUND` usually indicate outdated or missing Google Play components. The `APP_NOT_OWNED` error means the app was not installed by Google Play. Check the `ErrorCode` enum in the [API](#api) section for the full list of error codes.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API and App Attest.
- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request user authorization via Apple's App Tracking Transparency framework.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/age-signals/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/age-signals/LICENSE).

# Capacitor Alarm Plugin

Capacitor plugin to create system alarms and timers.

## Features

- ⏰ **Real system alarms**: Create alarms that break through Silent Mode and Focus — unlike local notifications.
- ⏲️ **Timers**: Create countdown timers in the system clock app on Android.
- 📋 **Alarm management**: List and cancel the alarms created by your app on iOS.
- 🍏 **AlarmKit**: One of the first plugins to support Apple's new AlarmKit framework on iOS 26.
- 🔐 **Permissions**: Check and request the alarm authorization with a single call.
- 🤝 **Compatibility**: Works alongside the [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/), [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) and [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Alarm plugin is typically used when the user must be reliably interrupted at a specific time, for example:

- **Wake-up alarms**: Create alarms that break through Silent Mode and Focus, for example for morning routines in sleep or fitness apps.
- **Recurring reminders**: Repeat alarms on specific weekdays, such as a medication reminder every Monday and Friday.
- **Countdown timers**: Start timers in the system clock app on Android, for example for cooking or workout apps.
- **Alarm management**: List and cancel the alarms created by your app on iOS to build your own alarm overview.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-alarm` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-alarm
npx cap sync
```

### Android

The plugin already declares the `com.android.alarm.permission.SET_ALARM` permission in its manifest. This is a normal permission that is granted automatically, so no additional configuration is required.

### iOS

This plugin uses Apple's [AlarmKit](https://developer.apple.com/documentation/alarmkit) framework, which requires **iOS 26 or later**. On older versions, all methods except `isAvailable()` reject as unavailable.

Add the `NSAlarmKitUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why the app needs to schedule alarms:

```
<key>NSAlarmKitUsageDescription</key>
<string>The app uses alarms to notify you at the times you choose.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check availability, check and request permissions, create alarms and timers, list and cancel alarms, and open the system clock app.

### Check if alarms are available

Before creating an alarm, check if alarms are available on the device. On Android, this checks whether an app that can handle alarms is installed. On iOS, this returns `true` if the device runs iOS 26 or later:

```
import { Alarm } from '@capawesome/capacitor-alarm';

const isAvailable = async () => {
  const { available } = await Alarm.isAvailable();
  return available;
};
```

### Check and request permissions

Check and request the permission to schedule alarms. On Android, both methods always return `granted` since alarms are created via the system clock app:

```
import { Alarm } from '@capawesome/capacitor-alarm';

const checkPermissions = async () => {
  const { alarms } = await Alarm.checkPermissions();
  return alarms;
};

const requestPermissions = async () => {
  const { alarms } = await Alarm.requestPermissions();
  return alarms;
};
```

### Create an alarm

Create a one-time or repeating alarm by providing the hour, the minute, and optionally a label and the weekdays on which the alarm repeats. On Android, the alarm is created in the system clock app and the returned `id` is `null`. On iOS, the alarm is owned by your app and can be listed and canceled later:

```
import { Alarm, Weekday } from '@capawesome/capacitor-alarm';

const createAlarm = async () => {
  const { id } = await Alarm.createAlarm({
    hour: 6,
    minute: 30,
    label: 'Wake up',
    days: [Weekday.Monday, Weekday.Friday],
  });
  return id;
};
```

### Create a timer

Create a countdown timer in the system clock app by providing the duration in seconds. Only available on Android:

```
import { Alarm } from '@capawesome/capacitor-alarm';

const createTimer = async () => {
  await Alarm.createTimer({
    duration: 300,
    label: 'Tea',
  });
};
```

### List and cancel alarms

Get all alarms that were created by your app and cancel them by their identifier. Only available on iOS:

```
import { Alarm } from '@capawesome/capacitor-alarm';

const getAlarms = async () => {
  const { alarms } = await Alarm.getAlarms();
  return alarms;
};

const cancelAlarm = async (id: string) => {
  await Alarm.cancelAlarm({ id });
};
```

### Open the alarms in the system clock app

Open the list of alarms in the system clock app, for example so the user can review or edit an alarm. Only available on Android:

```
import { Alarm } from '@capawesome/capacitor-alarm';

const openAlarms = async () => {
  await Alarm.openAlarms();
};
```

## API

- [`cancelAlarm(...)`](#cancelalarm)
- [`checkPermissions()`](#checkpermissions)
- [`createAlarm(...)`](#createalarm)
- [`createTimer(...)`](#createtimer)
- [`getAlarms()`](#getalarms)
- [`isAvailable()`](#isavailable)
- [`openAlarms()`](#openalarms)
- [`requestPermissions()`](#requestpermissions)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### cancelAlarm(...)

```
cancelAlarm(options: CancelAlarmOptions) => Promise<void>
```

Cancel an alarm that was created by the app.

Only available on iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `CancelAlarmOptions` |

**Since:** 0.1.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permission to schedule alarms.

On Android, this method always returns `granted` since alarms are created via the system clock app.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### createAlarm(...)

```
createAlarm(options: CreateAlarmOptions) => Promise<CreateAlarmResult>
```

Create a new alarm.

On Android, the alarm is created in the system clock app. The app has no access to the created alarm afterwards.

On iOS, the alarm is owned by the app and can be listed and canceled using the `getAlarms(...)` and `cancelAlarm(...)` methods.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `CreateAlarmOptions` |

**Returns:** `Promise<CreateAlarmResult>`

**Since:** 0.1.0

______________________________________________________________________

### createTimer(...)

```
createTimer(options: CreateTimerOptions) => Promise<void>
```

Create a new countdown timer in the system clock app.

Only available on Android.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `CreateTimerOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getAlarms()

```
getAlarms() => Promise<GetAlarmsResult>
```

Get all alarms that were created by the app.

Only available on iOS.

**Returns:** `Promise<GetAlarmsResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if alarms are available on this device.

On Android, this checks whether an app that can handle alarms is installed. On iOS, this returns `true` if the device runs iOS 26 or later.

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### openAlarms()

```
openAlarms() => Promise<void>
```

Open the list of alarms in the system clock app.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to schedule alarms.

On Android, this method always returns `granted` since alarms are created via the system clock app.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CancelAlarmOptions

| Prop     | Type     | Description                                   | Since |
| -------- | -------- | --------------------------------------------- | ----- |
| **`id`** | `string` | The unique identifier of the alarm to cancel. | 0.1.0 |

#### PermissionStatus

| Prop         | Type              | Description                            | Since |
| ------------ | ----------------- | -------------------------------------- | ----- |
| **`alarms`** | `PermissionState` | Permission state of scheduling alarms. | 0.1.0 |

#### CreateAlarmResult

| Prop     | Type     | Description | Since                                                                                                                             |
| -------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **`id`** | \`string | null\`      | The unique identifier of the created alarm. On Android, this is always `null` since the alarm is created in the system clock app. |

#### CreateAlarmOptions

| Prop          | Type                        | Description                                                                                                                      | Since |
| ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`android`** | `CreateAlarmAndroidOptions` | Android-specific options. Only available on Android.                                                                             | 0.1.0 |
| **`days`**    | `Weekday[]`                 | The days of the week on which the alarm repeats. If not provided, the alarm fires once at the next occurrence of the given time. | 0.1.0 |
| **`hour`**    | `number`                    | The hour of the alarm (0-23).                                                                                                    | 0.1.0 |
| **`label`**   | `string`                    | The label of the alarm.                                                                                                          | 0.1.0 |
| **`minute`**  | `number`                    | The minute of the alarm (0-59).                                                                                                  | 0.1.0 |

#### CreateAlarmAndroidOptions

| Prop          | Type      | Description                                                                                                                                | Default | Since |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`skipUi`**  | `boolean` | Whether or not to create the alarm without showing the user interface of the system clock app. Only available on Android.                  | `false` | 0.1.0 |
| **`vibrate`** | `boolean` | Whether or not the alarm should vibrate. If not provided, the default behavior of the system clock app is used. Only available on Android. |         | 0.1.0 |

#### CreateTimerOptions

| Prop           | Type                        | Description                                          | Since |
| -------------- | --------------------------- | ---------------------------------------------------- | ----- |
| **`android`**  | `CreateTimerAndroidOptions` | Android-specific options. Only available on Android. | 0.1.0 |
| **`duration`** | `number`                    | The length of the timer in seconds (1-86400).        | 0.1.0 |
| **`label`**    | `string`                    | The label of the timer.                              | 0.1.0 |

#### CreateTimerAndroidOptions

| Prop         | Type      | Description                                                                                                               | Default | Since |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`skipUi`** | `boolean` | Whether or not to create the timer without showing the user interface of the system clock app. Only available on Android. | `false` | 0.1.0 |

#### GetAlarmsResult

| Prop         | Type          | Description                              | Since |
| ------------ | ------------- | ---------------------------------------- | ----- |
| **`alarms`** | `AlarmInfo[]` | The alarms that were created by the app. | 0.1.0 |

#### AlarmInfo

| Prop          | Type      | Description                         | Since                               |
| ------------- | --------- | ----------------------------------- | ----------------------------------- |
| **`enabled`** | \`boolean | null\`                              | Whether or not the alarm is active. |
| **`hour`**    | \`number  | null\`                              | The hour of the alarm (0-23).       |
| **`id`**      | `string`  | The unique identifier of the alarm. | 0.1.0                               |
| **`label`**   | \`string  | null\`                              | The label of the alarm.             |
| **`minute`**  | \`number  | null\`                              | The minute of the alarm (0-59).     |

#### IsAvailableResult

| Prop            | Type      | Description                                         | Since |
| --------------- | --------- | --------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not alarms are available on this device. | 0.1.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### Weekday

| Members         | Value         | Since |
| --------------- | ------------- | ----- |
| **`Friday`**    | `'FRIDAY'`    | 0.1.0 |
| **`Monday`**    | `'MONDAY'`    | 0.1.0 |
| **`Saturday`**  | `'SATURDAY'`  | 0.1.0 |
| **`Sunday`**    | `'SUNDAY'`    | 0.1.0 |
| **`Thursday`**  | `'THURSDAY'`  | 0.1.0 |
| **`Tuesday`**   | `'TUESDAY'`   | 0.1.0 |
| **`Wednesday`** | `'WEDNESDAY'` | 0.1.0 |

## Alarms vs. Local Notifications

Alarms are not the same as local notifications. Use an alarm when the user must be interrupted at a specific time, and a local notification for everything else.

|                             | Alarm | Local Notification |
| --------------------------- | ----- | ------------------ |
| Breaks through Silent Mode  | ✅    | ❌                 |
| Breaks through Focus modes  | ✅    | ❌                 |
| Plays sound until dismissed | ✅    | ❌                 |
| Custom content and actions  | ❌    | ✅                 |

## Platform Support

The two platforms have fundamentally different alarm models, which this plugin exposes honestly instead of hiding behind a false abstraction:

- **Android**: Alarms and timers are created in the **system clock app** via the [`AlarmClock`](https://developer.android.com/reference/android/provider/AlarmClock) intent API. This is fire-and-forget: once created, the alarm belongs to the clock app and the OS offers no API to list or cancel it. The `createAlarm(...)` method therefore returns `null` as the alarm identifier, and `getAlarms()` and `cancelAlarm(...)` reject as unimplemented.
- **iOS (26+)**: Alarms are created with [AlarmKit](https://developer.apple.com/documentation/alarmkit) and are **owned by your app**: you can list them with `getAlarms()` and cancel them with `cancelAlarm(...)`. Timers created with AlarmKit require a Live Activity widget extension in the app, which is why `createTimer(...)` is currently not supported on iOS. The `openAlarms()` method is not supported on iOS because the system clock app cannot be opened via a public API.

| Method                 | Android | iOS (26+) |
| ---------------------- | ------- | --------- |
| `cancelAlarm(...)`     | ❌      | ✅        |
| `checkPermissions()`   | ✅      | ✅        |
| `createAlarm(...)`     | ✅      | ✅        |
| `createTimer(...)`     | ✅      | ❌        |
| `getAlarms()`          | ❌      | ✅        |
| `isAvailable()`        | ✅      | ✅        |
| `openAlarms()`         | ✅      | ❌        |
| `requestPermissions()` | ✅      | ✅        |

## FAQ

### How is this plugin different from other similar plugins?

It creates real system alarms that break through Silent Mode and Focus and keep sounding until dismissed — one of the first plugins to adopt Apple's new AlarmKit on iOS 26 — with repeating weekday alarms, permission handling in a single call, timers via the system clock app on Android, and alarm listing and cancellation on iOS. It exposes each platform's fundamentally different alarm model honestly through a fully typed API and stays actively maintained against the latest Capacitor and OS versions. If a normal reminder is enough, a local notification is the simpler choice; if the user must be reliably interrupted at a set time, this plugin is built for that.

### Why does the plugin require iOS 26 or later?

The plugin uses Apple's [AlarmKit](https://developer.apple.com/documentation/alarmkit) framework, which was introduced with iOS 26. On older iOS versions, all methods except `isAvailable()` reject as unavailable, so you can use `isAvailable()` to check for support at runtime.

### Why can't I list or cancel alarms on Android?

On Android, alarms are created in the system clock app via the `AlarmClock` intent API, which is fire-and-forget: once created, the alarm belongs to the clock app and the OS offers no API to list or cancel it. That is why `createAlarm(...)` returns `null` as the alarm identifier on Android and `getAlarms()` and `cancelAlarm(...)` reject as unimplemented. See the [Platform Support](#platform-support) section for details.

### What is the difference between an alarm and a local notification?

An alarm breaks through Silent Mode and Focus modes and plays a sound until it is dismissed, while a local notification does not. On the other hand, local notifications support custom content and actions. Use an alarm when the user must be interrupted at a specific time, and a local notification for everything else (see [Alarms vs. Local Notifications](#alarms-vs-local-notifications)).

### Why is creating timers not supported on iOS?

Timers created with AlarmKit require a Live Activity widget extension in the app, which is why `createTimer(...)` is currently not supported on iOS. On Android, timers are created in the system clock app.

### Do I need any permissions to create alarms?

On Android, the plugin already declares the `com.android.alarm.permission.SET_ALARM` permission in its manifest, which is granted automatically. On iOS, you must add the `NSAlarmKitUsageDescription` key to your `Info.plist` file (see [Installation](#installation)) and request the alarm authorization using `requestPermissions()`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/): Run background tasks in your app.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Let the user pick the alarm time with a native date and time picker.
- [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/): Detect whether the device is in silent mode.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/alarm/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/alarm/LICENSE).

# Capacitor Android Battery Optimization Plugin

Capacitor plugin for Android to manage battery optimization settings, request exemptions, and enhance app performance under Doze and App Standby modes.

## Use Cases

The Android Battery Optimization plugin is typically used by apps whose core function is affected by Doze and App Standby, for example:

- **Background reliability checks**: Detect whether battery optimization is enabled and inform the user that background work may be deferred.
- **Guided settings flow**: Open the battery optimization settings page so the user can manually exclude your app from battery optimization.
- **Direct exemption requests**: Request the battery optimization ignore permission when the core function of your app is adversely affected by Power Management features.
- **Troubleshooting support**: Help users understand why they receive delayed updates from your app by checking the battery optimization status.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

| Android |
| ------- |
|         |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-android-battery-optimization` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-android-battery-optimization
npx cap sync
```

### Android

This API requires the following permissions be added to your `AndroidManifest.xml` before the `application` tag if you want to request direct exemption from Power Management features:

```
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
```

⚠️ **Attention**: Google Play policies prohibit apps from requesting direct exemption from Power Management features in Android 6.0+ (Doze and App Standby) unless the core function of the app is adversely affected. [Source](https://developer.android.com/training/monitoring-device-state/doze-standby.html#support_for_other_use_cases)

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether battery optimization is enabled, open the battery optimization settings, and request an exemption from battery optimization.

### Check if battery optimization is enabled

Find out whether battery optimization is enabled for the device, for example to inform the user that background work may be deferred. All methods of this plugin are only available on Android, so guard your calls with a platform check:

```
import { BatteryOptimization } from '@capawesome-team/capacitor-android-battery-optimization';
import { Capacitor } from '@capacitor/core';

const isBatteryOptimizationEnabled = async () => {
  if (Capacitor.getPlatform() !== 'android') {
    return false;
  }
  const { enabled } = await BatteryOptimization.isBatteryOptimizationEnabled();
  return enabled;
};
```

### Open the battery optimization settings

Open the battery optimization settings page so the user can manually exclude your app from battery optimization:

```
import { BatteryOptimization } from '@capawesome-team/capacitor-android-battery-optimization';
import { Capacitor } from '@capacitor/core';

const openBatteryOptimizationSettings = async () => {
  if (Capacitor.getPlatform() !== 'android') {
    return;
  }
  await BatteryOptimization.openBatteryOptimizationSettings();
};
```

### Request an exemption from battery optimization

Request the battery optimization ignore permission directly. This method requires the `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` manifest permission (see [Installation](#installation)) and should only be used if your app meets an acceptable use case according to the Google Play policy:

```
import { BatteryOptimization } from '@capawesome-team/capacitor-android-battery-optimization';
import { Capacitor } from '@capacitor/core';

const requestIgnoreBatteryOptimization = async () => {
  if (Capacitor.getPlatform() !== 'android') {
    return;
  }
  await BatteryOptimization.requestIgnoreBatteryOptimization();
};
```

## API

- [`isBatteryOptimizationEnabled()`](#isbatteryoptimizationenabled)
- [`openBatteryOptimizationSettings()`](#openbatteryoptimizationsettings)
- [`requestIgnoreBatteryOptimization()`](#requestignorebatteryoptimization)
- [Interfaces](#interfaces)

### isBatteryOptimizationEnabled()

```
isBatteryOptimizationEnabled() => Promise<IsBatteryOptimizationEnabledResult>
```

Returns whether or not battery optimization is enabled.

Only available on Android.

**Returns:** `Promise<IsBatteryOptimizationEnabledResult>`

**Since:** 0.0.1

______________________________________________________________________

### openBatteryOptimizationSettings()

```
openBatteryOptimizationSettings() => Promise<void>
```

Opens the battery optimization settings page.

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### requestIgnoreBatteryOptimization()

```
requestIgnoreBatteryOptimization() => Promise<void>
```

Requests the battery optimization ignore permission. This method needs the `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` manifest permission. Use this method only if your app meets an acceptable use case (see Google Play Policy).

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### IsBatteryOptimizationEnabledResult

| Prop          | Type      | Description                                     | Since |
| ------------- | --------- | ----------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether or not battery optimization is enabled. | 0.0.1 |

## FAQ

### Does this plugin work on iOS or the Web?

No, all methods of this plugin are only available on Android, since battery optimization with Doze and App Standby is an Android concept. On other platforms, guard your calls with a platform check using `Capacitor.getPlatform()` as shown in the [usage examples](#usage).

### What is the difference between opening the settings and requesting an exemption?

The `openBatteryOptimizationSettings()` method opens the battery optimization settings page, where the user has to find and exclude your app manually. The `requestIgnoreBatteryOptimization()` method asks the user directly to exempt your app, but requires the `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` manifest permission and is subject to Google Play policy restrictions.

### Do I need to add any permissions to my app?

Only if you want to use `requestIgnoreBatteryOptimization()`. In that case, add the `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` permission to your `AndroidManifest.xml` as described in the [Installation](#installation) section. Checking the battery optimization status and opening the settings page do not require any permissions.

### Can requesting an exemption get my app rejected from Google Play?

Google Play policies prohibit apps from requesting direct exemption from Power Management features in Android 6.0+ (Doze and App Standby) unless the core function of the app is adversely affected. Use `requestIgnoreBatteryOptimization()` only if your app meets an acceptable use case, or open the battery optimization settings with `openBatteryOptimizationSettings()` instead. See the [Android documentation](https://developer.android.com/training/monitoring-device-state/doze-standby.html#support_for_other_use_cases) for more information.

### Why is background work in my app delayed on Android?

When battery optimization is enabled, Android defers background work under Doze and App Standby, which can delay tasks your app performs in the background. You can use `isBatteryOptimizationEnabled()` to detect this and guide the user to exclude your app from battery optimization.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Run a foreground service on Android.
- [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/): Run background tasks in your app.
- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/): Access battery information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-battery-optimization/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-battery-optimization/LICENSE).

# Capacitor Android Dark Mode Support Plugin

Capacitor plugin for seamless Android dark mode support. Enhance user experience with `prefers-color-scheme` CSS media feature compatibility.

## Use Cases

The Android Dark Mode Support plugin is typically used whenever an app should respect the system-wide dark mode setting on Android, for example:

- **Automatic dark theme switching**: Apply dark styles with `prefers-color-scheme` CSS media queries that correctly reflect the Android system setting.
- **Consistent theming**: Ensure the web view of your Capacitor app matches the user's system-wide dark mode preference without a manual in-app toggle.
- **Framework theming**: Let UI frameworks whose dark themes rely on the `prefers-color-scheme` media feature switch themes correctly on Android.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-android-dark-mode-support` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-android-dark-mode-support
npx cap sync
```

### Android

#### 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:

- `$androidxWebkitVersion` version of `androidx.webkit:webkit` (default: `1.9.0`)

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

## Configuration

No configuration required for this plugin.

## Usage

The plugin only needs to be installed.

It enables the correct behavior of the [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) CSS media feature.

## FAQ

### Why does `prefers-color-scheme` not work in my Capacitor app on Android?

By default, the `prefers-color-scheme` CSS media feature may not correctly reflect the system dark mode setting in the Android web view. This plugin enables the correct behavior of the media feature so that your CSS dark mode styles are applied when the user has enabled dark mode on their device.

### Do I need to call any methods to use this plugin?

No, the plugin only needs to be installed. Once installed, it enables the correct behavior of the `prefers-color-scheme` CSS media feature without any additional code. See the [Usage](#usage) section for more information.

### Does this plugin work on iOS or Web?

No, this plugin only provides an Android implementation, as the name suggests. It exists to fix the dark mode behavior of the Android web view.

### Can I change the version of the `androidx.webkit` dependency?

Yes, you can define the `$androidxWebkitVersion` project variable in your app's `variables.gradle` file to change the default version (`1.9.0`) of the `androidx.webkit:webkit` dependency. This can be useful if you encounter dependency conflicts with other plugins in your project.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/): Read the user's system accessibility preferences.
- [Android Edge-to-Edge Support](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/): Support edge-to-edge display on Android and set the background color of the status bar and navigation bar.
- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/): Set the background color and button style of the navigation bar.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-dark-mode-support/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-dark-mode-support/LICENSE).

# Capacitor Android Edge-to-Edge Support Plugin

Capacitor plugin to support [edge-to-edge](https://developer.android.com/develop/ui/views/layout/edge-to-edge) display on Android with advanced features like setting the background color of the status bar and navigation bar.

| Before | After | Before | After |
| ------ | ----- | ------ | ----- |
|        |       |        |       |

**Attention:** Despite its name, this plugin doesn't enable edge-to-edge mode by default. Instead, it preserves the traditional app behavior by applying proper insets to the webview, preventing Android's edge-to-edge changes from affecting apps that haven't been designed to support it.

## Use Cases

The Android Edge-to-Edge Support plugin is typically used whenever an app needs to deal with Android's edge-to-edge display behavior, for example:

- **Preserving traditional layouts**: Prevent Android's edge-to-edge changes from affecting apps that haven't been designed to support it by applying proper insets to the web view.
- **Styling the system bars**: Set the background color of the status bar and navigation bar so they match your app's design.
- **Switching between light and dark themes**: Update the system bar background colors together with the [SystemBars](https://capacitorjs.com/docs/apis/system-bars) plugin when the user changes the theme.
- **Custom inset handling**: Read the insets that are currently applied to the web view to fine-tune your own layout.

## Compatibility

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

## Guides

- [Capacitor Edge-to-Edge & Safe Areas: The Complete Guide](https://capawesome.io/blog/capacitor-edge-to-edge-and-safe-areas-guide/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-android-edge-to-edge-support` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-android-edge-to-edge-support
npx cap sync
```

### Android

#### Capacitor SystemBars Plugin

Make sure to disable the built-in insets handling of the [Capacitor SystemBars](https://capacitorjs.com/docs/apis/system-bars) plugin in your [Capacitor Configuration](https://capacitorjs.com/docs/config) file:

```
{
  "plugins": {
    "SystemBars": {
      "insetsHandling": "disable"
    }
  }
}
```

Please note that this plugin is part of the Capacitor core and the insets handling is **always enabled by default**.

#### Capacitor Keyboard Plugin

If you are using the [Capacitor Keyboard](https://capacitorjs.com/docs/apis/keyboard) plugin, make sure to set the `resizeOnFullScreen` property to `false` (default) in your [Capacitor Configuration](https://capacitorjs.com/docs/config) file:

```
{
  "plugins": {
    "Keyboard": {
      "resizeOnFullScreen": false
    }
  }
}
```

Otherwise, the web view will be resized to fit the screen, which may cause issues with this plugin, see [this comment](https://github.com/capawesome-team/capacitor-plugins/issues/490#issuecomment-2826435796).

## Configuration

| Prop                     | Type     | Description                                                                                                 | Since |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------- | ----- |
| **`backgroundColor`**    | `string` | The hexadecimal color to set as the background color of the status bar and navigation bar.                  | 7.1.0 |
| **`navigationBarColor`** | `string` | The hexadecimal color to set as the background color of the navigation bar area. Only available on Android. | 8.0.0 |
| **`statusBarColor`**     | `string` | The hexadecimal color to set as the background color of the status bar area. Only available on Android.     | 8.0.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "EdgeToEdge": {
      "backgroundColor": "#ffffff",
      "navigationBarColor": "#000000",
      "statusBarColor": "#ffffff"
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-android-edge-to-edge-support" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    EdgeToEdge: {
      backgroundColor: "#ffffff",
      navigationBarColor: "#000000",
      statusBarColor: "#ffffff",
    },
  },
};

export default config;
```

## Usage

The plugin applies insets to the web view automatically once installed; the following examples show how to enable or disable the edge-to-edge mode, read the applied insets, and set the system bar colors for light and dark themes.

### Enable or disable the edge-to-edge mode

Enable or disable the edge-to-edge mode at runtime. Only available on Android:

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';

const enable = async () => {
  await EdgeToEdge.enable();
};

const disable = async () => {
  await EdgeToEdge.disable();
};
```

### Get the applied insets

Read the insets that are currently applied to the web view, for example to fine-tune your own layout. Only available on Android:

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';

const getInsets = async () => {
  const result = await EdgeToEdge.getInsets();
  console.log('Insets:', result);
};
```

### Set the system bar colors for light and dark themes

Set the background color of the status bar and navigation bar, for example when the user switches between a light and a dark theme. It's recommended to combine this with the `setStyle(...)` method of the [SystemBars](https://capacitorjs.com/docs/apis/system-bars) plugin so the system bar icons remain readable:

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';
import { SystemBars, SystemBarsStyle } from '@capacitor/core';

const setDarkStyle = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
  await EdgeToEdge.setBackgroundColor({ color: '#000000' });
};

const setLightStyle = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Light });
  await EdgeToEdge.setBackgroundColor({ color: '#FFFFFF' });
};
```

## API

- [`disable()`](#disable)
- [`enable()`](#enable)
- [`getInsets()`](#getinsets)
- [`setBackgroundColor(...)`](#setbackgroundcolor)
- [`setNavigationBarColor(...)`](#setnavigationbarcolor)
- [`setStatusBarColor(...)`](#setstatusbarcolor)
- [Interfaces](#interfaces)

### disable()

```
disable() => Promise<void>
```

Disable the edge-to-edge mode.

Only available on Android.

**Since:** 7.2.0

______________________________________________________________________

### enable()

```
enable() => Promise<void>
```

Enable the edge-to-edge mode.

Only available on Android.

**Since:** 7.2.0

______________________________________________________________________

### getInsets()

```
getInsets() => Promise<GetInsetsResult>
```

Return the insets that are currently applied to the webview.

Only available on Android.

**Returns:** `Promise<GetInsetsResult>`

**Since:** 7.2.0

______________________________________________________________________

### setBackgroundColor(...)

```
setBackgroundColor(options: SetBackgroundColorOptions) => Promise<void>
```

Set the background color of the status bar and navigation bar.

Only available on Android.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SetBackgroundColorOptions` |

**Since:** 7.0.0

______________________________________________________________________

### setNavigationBarColor(...)

```
setNavigationBarColor(options: SetNavigationBarColorOptions) => Promise<void>
```

Set the background color of the navigation bar area.

Only available on Android.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SetNavigationBarColorOptions` |

**Since:** 8.0.0

______________________________________________________________________

### setStatusBarColor(...)

```
setStatusBarColor(options: SetStatusBarColorOptions) => Promise<void>
```

Set the background color of the status bar area.

Only available on Android.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `SetStatusBarColorOptions` |

**Since:** 8.0.0

______________________________________________________________________

### Interfaces

#### GetInsetsResult

| Prop         | Type     | Description                                                                  | Since |
| ------------ | -------- | ---------------------------------------------------------------------------- | ----- |
| **`bottom`** | `number` | The bottom inset that was applied to the webview. Only available on Android. | 7.2.0 |
| **`left`**   | `number` | The left inset that was applied to the webview. Only available on Android.   | 7.2.0 |
| **`right`**  | `number` | The right inset that was applied to the webview. Only available on Android.  | 7.2.0 |
| **`top`**    | `number` | The top inset that was applied to the webview. Only available on Android.    | 7.2.0 |

#### SetBackgroundColorOptions

| Prop        | Type     | Description                                                                                | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------ | ----- |
| **`color`** | `string` | The hexadecimal color to set as the background color of the status bar and navigation bar. | 7.0.0 |

#### SetNavigationBarColorOptions

| Prop        | Type     | Description                                                                      | Since |
| ----------- | -------- | -------------------------------------------------------------------------------- | ----- |
| **`color`** | `string` | The hexadecimal color to set as the background color of the navigation bar area. | 8.0.0 |

#### SetStatusBarColorOptions

| Prop        | Type     | Description                                                                  | Since |
| ----------- | -------- | ---------------------------------------------------------------------------- | ----- |
| **`color`** | `string` | The hexadecimal color to set as the background color of the status bar area. | 8.0.0 |

## FAQ

### What about Capacitor 8's built-in edge-to-edge support?

Capacitor 8 introduced native edge-to-edge functionality through the internal `SystemBars` plugin. While this covers many common scenarios, this plugin addresses additional edge cases that aren't yet fully resolved in the Capacitor core implementation. We plan to deprecate this plugin once all edge cases are properly handled in Capacitor core.

### Is this plugin compatible with Capacitor's SystemBars API?

Yes, this plugin is partially compatible with the new [SystemBars API](https://capacitorjs.com/docs/apis/system-bars) introduced in Capacitor 8. For example, methods like `setStyle()` from the SystemBars API are supported and can be used alongside this plugin without conflicts.

### Does this plugin enable edge-to-edge mode by default?

No, despite its name, this plugin doesn't enable edge-to-edge mode by default. Instead, it preserves the traditional app behavior by applying proper insets to the web view, preventing Android's edge-to-edge changes from affecting apps that haven't been designed to support it. You can still enable or disable the edge-to-edge mode at runtime using the `enable()` and `disable()` methods.

### Why does my layout break when the keyboard is displayed?

If you are using the [Capacitor Keyboard](https://capacitorjs.com/docs/apis/keyboard) plugin, make sure the `resizeOnFullScreen` property is set to `false` (the default) in your Capacitor configuration file. Otherwise, the web view will be resized to fit the screen, which may cause issues with this plugin. See the [Installation](#installation) section for more information.

### Does this plugin work on iOS or Web?

No, this plugin only provides an Android implementation, as the name suggests. All methods are only available on Android since it addresses Android's edge-to-edge display behavior.

## Related Plugins

- [Android Dark Mode Support](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/): Support dark mode on Android via the `prefers-color-scheme` CSS media feature.
- [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/): Hide and show the iOS home indicator.
- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/): Set the background color and button style of the navigation bar.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-edge-to-edge-support/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-edge-to-edge-support/LICENSE).

# Capacitor Android Foreground Service Plugin

Capacitor plugin to run a foreground service on Android.

## Use Cases

The Android Foreground Service plugin is typically used whenever an app needs to keep running a task while it is in the background, for example:

- **Location tracking**: Run long-running use cases that require location access, such as navigation or location sharing, using the `Location` service type.
- **Audio recording**: Continue microphone capture from the background, such as voice recorders or communication apps, using the `Microphone` service type.
- **Long-running tasks with user awareness**: Show a persistent notification with a title, body, and icon while your app performs work in the background.
- **Interactive notifications**: Add buttons to the foreground service notification and react to them via the `buttonClicked` event.
- **Bringing the app back to the foreground**: Move the app to the foreground programmatically, for example in response to a notification button click.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

| Android |
| ------- |
|         |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-android-foreground-service` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-android-foreground-service
npx cap sync
```

### Android

This API requires the following permissions be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<!-- Required to keep the app running in the background without any ressource limitations -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required to request the manage overlay permission -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
```

**Attention**: Replace `FOREGROUND_SERVICE_LOCATION` with the foreground service types you want to use (see [Foreground service types](https://developer.android.com/develop/background-work/services/fg-service-types)). See [ServiceType](#servicetype) for the available types.

You also need to add the following receiver and service **inside** the `application` tag in your `AndroidManifest.xml`:

```
<receiver android:name="io.capawesome.capacitorjs.plugins.foregroundservice.NotificationActionBroadcastReceiver" />
<service android:name="io.capawesome.capacitorjs.plugins.foregroundservice.AndroidForegroundService" android:foregroundServiceType="location" />
```

**Attention**: Replace `location` with the foreground service types you want to use (see [Foreground service types](https://developer.android.com/develop/background-work/services/fg-service-types)). See [ServiceType](#servicetype) for the available types.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to start, update, and stop a foreground service and how to create and delete notification channels.

### Start a foreground service

Start the foreground service with a persistent notification. You can optionally add buttons to the notification, which trigger the `buttonClicked` event when tapped. Only available on Android:

```
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

const startForegroundService = async () => {
  await ForegroundService.startForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
    buttons: [
      {
        title: 'Button 1',
        id: 1,
      },
      {
        title: 'Button 2',
        id: 2,
      },
    ],
    silent: false,
    notificationChannelId: 'default',
  });
};
```

### Update the foreground service notification

Update the notification details of the running foreground service, for example to show the progress of a task. Only available on Android:

```
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

const updateForegroundService = async () => {
  await ForegroundService.updateForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
  });
};
```

### Stop the foreground service

Stop the running foreground service when the background work is done. Only available on Android:

```
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

const stopForegroundService = async () => {
  await ForegroundService.stopForegroundService();
};
```

### Create and delete notification channels

Create a notification channel for the foreground service notification. If not invoked, the plugin creates a channel with name and description set to "Default". Only available on Android (SDK 26+):

```
import { ForegroundService, Importance } from '@capawesome-team/capacitor-android-foreground-service';

const createNotificationChannel = async () => {
  await ForegroundService.createNotificationChannel({
    id: 'default',
    name: 'Default',
    description: 'Default channel',
    importance: Importance.Default,
  });
};

const deleteNotificationChannel = async () => {
  await ForegroundService.deleteNotificationChannel({
    id: 'default',
  });
};
```

## API

- [`moveToForeground()`](#movetoforeground)
- [`startForegroundService(...)`](#startforegroundservice)
- [`updateForegroundService(...)`](#updateforegroundservice)
- [`stopForegroundService()`](#stopforegroundservice)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`checkManageOverlayPermission()`](#checkmanageoverlaypermission)
- [`requestManageOverlayPermission()`](#requestmanageoverlaypermission)
- [`createNotificationChannel(...)`](#createnotificationchannel)
- [`deleteNotificationChannel(...)`](#deletenotificationchannel)
- [`addListener('buttonClicked', ...)`](#addlistenerbuttonclicked-)
- [`addListener('notificationTapped', ...)`](#addlistenernotificationtapped-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### moveToForeground()

```
moveToForeground() => Promise<void>
```

Moves the app to the foreground.

On Android SDK 23+, the user must grant the manage overlay permission. You can use the `requestManageOverlayPermission()` method to request the permission and the `checkManageOverlayPermission()` method to check if the permission is granted.

Only available on Android.

**Since:** 0.3.0

______________________________________________________________________

### startForegroundService(...)

```
startForegroundService(options: StartForegroundServiceOptions) => Promise<void>
```

Starts the foreground service.

Only available on Android.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `StartForegroundServiceOptions` |

**Since:** 0.0.1

______________________________________________________________________

### updateForegroundService(...)

```
updateForegroundService(options: UpdateForegroundServiceOptions) => Promise<void>
```

Updates the notification details of the running foreground service.

Only available on Android.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `StartForegroundServiceOptions` |

**Since:** 6.1.0

______________________________________________________________________

### stopForegroundService()

```
stopForegroundService() => Promise<void>
```

Stops the foreground service.

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permission to display notifications.

On **Android**, this method only needs to be called on Android 13+.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 5.0.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to display notifications.

On **Android**, this method only needs to be called on Android 13+.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 5.0.0

______________________________________________________________________

### checkManageOverlayPermission()

```
checkManageOverlayPermission() => Promise<ManageOverlayPermissionResult>
```

Check if the overlay permission is granted.

Only available on Android.

**Returns:** `Promise<ManageOverlayPermissionResult>`

**Since:** 0.3.0

______________________________________________________________________

### requestManageOverlayPermission()

```
requestManageOverlayPermission() => Promise<ManageOverlayPermissionResult>
```

Request the manage overlay permission.

Only available on Android.

**Returns:** `Promise<ManageOverlayPermissionResult>`

**Since:** 0.3.0

______________________________________________________________________

### createNotificationChannel(...)

```
createNotificationChannel(options: CreateNotificationChannelOptions) => Promise<void>
```

Create a notification channel. If not invoked, the plugin creates a channel with name and description set to "Default".

Only available for Android (SDK 26+).

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `CreateNotificationChannelOptions` |

**Since:** 6.1.0

______________________________________________________________________

### deleteNotificationChannel(...)

```
deleteNotificationChannel(options: DeleteNotificationChannelOptions) => Promise<void>
```

Delete a notification channel.

Only available for Android (SDK 26+).

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `DeleteNotificationChannelOptions` |

**Since:** 6.1.0

______________________________________________________________________

### addListener('buttonClicked', ...)

```
addListener(eventName: 'buttonClicked', listenerFunc: ButtonClickedEventListener) => Promise<PluginListenerHandle>
```

Called when a notification button is clicked.

Only available on iOS.

| Param              | Type                         |
| ------------------ | ---------------------------- |
| **`eventName`**    | `'buttonClicked'`            |
| **`listenerFunc`** | `ButtonClickedEventListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.0

______________________________________________________________________

### addListener('notificationTapped', ...)

```
addListener(eventName: 'notificationTapped', listenerFunc: NotificationTappedEventListener) => Promise<PluginListenerHandle>
```

Called when the foreground service notification is tapped.

Only available on Android.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'notificationTapped'`            |
| **`listenerFunc`** | `NotificationTappedEventListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.2.0

______________________________________________________________________

### Interfaces

#### StartForegroundServiceOptions

| Prop                        | Type                   | Description                                                                                                                                                                                                     | Default | Since |
| --------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`body`**                  | `string`               | The body of the notification, shown below the title.                                                                                                                                                            |         | 0.0.1 |
| **`buttons`**               | `NotificationButton[]` | The buttons to show on the notification. Only available on Android (SDK 24+).                                                                                                                                   |         | 0.2.0 |
| **`id`**                    | `number`               | The notification identifier.                                                                                                                                                                                    |         | 0.0.1 |
| **`serviceType`**           | `ServiceType`          | The foreground service type. Only available on Android (SDK 29+).                                                                                                                                               |         | 6.2.0 |
| **`smallIcon`**             | `string`               | The status bar icon for the notification. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. |         | 0.0.1 |
| **`title`**                 | `string`               | The title of the notification.                                                                                                                                                                                  |         | 0.0.1 |
| **`silent`**                | `boolean`              | If true, will only alert (sound/vibration) on the first notification. Subsequent updates will be silent.                                                                                                        | `false` | 6.1.0 |
| **`notificationChannelId`** | `string`               | The notification channel identifier.                                                                                                                                                                            |         | 6.1.0 |

#### NotificationButton

| Prop        | Type     | Description                                                                                           | Since |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------- | ----- |
| **`title`** | `string` | The button title.                                                                                     | 0.2.0 |
| **`id`**    | `number` | The button identifier. This is used to identify the button when the `buttonClicked` event is emitted. | 0.2.0 |

#### PermissionStatus

| Prop          | Type              | Description                                   | Since |
| ------------- | ----------------- | --------------------------------------------- | ----- |
| **`display`** | `PermissionState` | Permission state of displaying notifications. | 5.0.0 |

#### ManageOverlayPermissionResult

| Prop          | Type      | Description                                                                   | Since |
| ------------- | --------- | ----------------------------------------------------------------------------- | ----- |
| **`granted`** | `boolean` | Whether the permission is granted. This is always `true` on Android SDK < 23. | 0.3.0 |

#### CreateNotificationChannelOptions

| Prop              | Type         | Description                                                         | Since |
| ----------------- | ------------ | ------------------------------------------------------------------- | ----- |
| **`description`** | `string`     | The description of this channel (presented to the user).            | 6.1.0 |
| **`id`**          | `string`     | The channel identifier.                                             | 6.1.0 |
| **`importance`**  | `Importance` | The level of interruption for notifications posted to this channel. | 6.1.0 |
| **`name`**        | `string`     | The name of this channel (presented to the user).                   | 6.1.0 |

#### DeleteNotificationChannelOptions

| Prop     | Type     | Description             | Since |
| -------- | -------- | ----------------------- | ----- |
| **`id`** | `string` | The channel identifier. | 6.1.0 |

#### PluginListenerHandle

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

#### ButtonClickedEvent

| Prop           | Type     | Description            | Since |
| -------------- | -------- | ---------------------- | ----- |
| **`buttonId`** | `number` | The button identifier. | 0.2.0 |

#### NotificationTappedEvent

| Prop                 | Type     | Description                  | Since |
| -------------------- | -------- | ---------------------------- | ----- |
| **`notificationId`** | `number` | The notification identifier. | 8.1.0 |

### Type Aliases

#### UpdateForegroundServiceOptions

`StartForegroundServiceOptions`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### ButtonClickedEventListener

`(event: ButtonClickedEvent): void`

#### NotificationTappedEventListener

`(event: NotificationTappedEvent): void`

### Enums

#### ServiceType

| Members          | Value | Description                                                                                     | Since |
| ---------------- | ----- | ----------------------------------------------------------------------------------------------- | ----- |
| **`Location`**   | `8`   | Long-running use cases that require location access, such as navigation and location sharing.   | 6.2.0 |
| **`Microphone`** | `128` | Continue microphone capture from the background, such as voice recorders or communication apps. | 6.2.0 |

#### Importance

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`Min`**     | `1`   | 6.1.0 |
| **`Low`**     | `2`   | 6.1.0 |
| **`Default`** | `3`   | 6.1.0 |
| **`High`**    | `4`   | 6.1.0 |
| **`Max`**     | `5`   | 6.1.0 |

## FAQ

### Why can the user dismiss the notification?

Android 14 has changed the behavior to allow users to dismiss such notifications, see [Changes to how users experience non-dismissible notifications](https://developer.android.com/about/versions/14/behavior-changes-all#non-dismissable-notifications).

### Which permissions does this plugin require?

You need to add the `FOREGROUND_SERVICE` permission along with the permission for each foreground service type you use (for example `FOREGROUND_SERVICE_LOCATION`) to your `AndroidManifest.xml`, see the [Installation](#installation) section. On Android 13+, you should also use `checkPermissions()` and `requestPermissions()` to request the permission to display notifications.

### Why does `moveToForeground` not work?

On Android SDK 23+, the user must grant the manage overlay permission before the app can be moved to the foreground. Use the `requestManageOverlayPermission()` method to request the permission and the `checkManageOverlayPermission()` method to check whether it has been granted.

### Which foreground service types are supported?

The plugin currently supports the `Location` service type for long-running use cases that require location access and the `Microphone` service type for continued microphone capture from the background. Make sure to declare the matching permission and the `android:foregroundServiceType` attribute in your `AndroidManifest.xml`, see the [Installation](#installation) section.

### Does this plugin work on iOS or Web?

No, this plugin only provides an Android implementation, as the name suggests. Foreground services are an Android concept and all methods are only available on Android.

## Related Plugins

- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions on Android.
- [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/): Run background tasks in your Capacitor app.
- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake while your app is in use.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/LICENSE).

# Capacitor Android Intent Launcher Plugin

Capacitor plugin to launch arbitrary Android intents.

## Features

- 🚀 **Start activities**: Launch any Android activity via a custom intent and read its result.
- 🔍 **Resolve activities**: Check whether an activity can handle an intent before launching it.
- 🎯 **Explicit & implicit intents**: Target a specific component or let the system pick a handler.
- 📦 **Extras & flags**: Attach primitive extras and intent flags.
- 🤝 **Compatibility**: Works alongside the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) and [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Android Intent Launcher plugin is typically used whenever an app needs to interact with system screens or other apps that no dedicated plugin covers, for example:

- **Opening system screens**: Open Android system screens such as the app settings screen via the `android.settings.APPLICATION_DETAILS_SETTINGS` action.
- **Integrating with other apps**: Launch a specific activity of another app via an explicit intent and read its result code and result data once it finishes.
- **Sharing and composing**: Share plain text via the `android.intent.action.SEND` action or compose an email via the `android.intent.action.SENDTO` action.
- **Feature detection**: Check whether an activity exists that can handle an intent before launching it, for example to conditionally show a button in your UI.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-android-intent-launcher` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-android-intent-launcher
npx cap sync
```

This plugin is only available on **Android**. On iOS and Web, all methods reject as unimplemented.

### Android

No additional configuration is required for this plugin.

However, on Android 11 (API level 30) and higher, [package visibility](https://developer.android.com/training/package-visibility) restricts which apps and intents your app can see. To launch or resolve intents that target other apps, you may need to declare matching [`<queries>`](https://developer.android.com/guide/topics/manifest/queries-element) entries in your app's `AndroidManifest.xml`. See [Package visibility](#package-visibility) below.

### iOS

This plugin has **no iOS implementation**. Intents are an Android-only concept. All methods reject as unimplemented on iOS.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to start an activity for an intent and check whether an intent can be resolved.

### Start an activity

Launch an activity for the given intent. The intent is started via the `startActivityForResult(...)` API, so the result code and result data of the launched activity are returned once it finishes. Only available on Android:

```
import { AndroidIntentLauncher } from '@capawesome/capacitor-android-intent-launcher';

const startActivity = async () => {
  const { resultCode } = await AndroidIntentLauncher.startActivity({
    action: 'android.intent.action.VIEW',
    dataUri: 'https://capawesome.io',
  });
  return resultCode;
};
```

### Check whether an intent can be resolved

Check whether an activity exists that can handle the given intent before launching it. On Android 11 (API level 30) and higher, the result is affected by [package visibility](#package-visibility). Only available on Android:

```
import { AndroidIntentLauncher } from '@capawesome/capacitor-android-intent-launcher';

const canResolveActivity = async () => {
  const { canResolve } = await AndroidIntentLauncher.canResolveActivity({
    action: 'android.intent.action.VIEW',
    dataUri: 'https://capawesome.io',
  });
  return canResolve;
};
```

## API

- [`canResolveActivity(...)`](#canresolveactivity)
- [`startActivity(...)`](#startactivity)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### canResolveActivity(...)

```
canResolveActivity(options: CanResolveActivityOptions) => Promise<CanResolveActivityResult>
```

Check whether an activity exists that can handle the given intent.

This is a wrapper around the `PackageManager.resolveActivity(...)` API.

On Android 11 (API level 30) and higher, the result is affected by package visibility. Your app may need to declare matching `&lt;queries&gt;` entries in its `AndroidManifest.xml` for the intent to be resolved.

Only available on Android.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartActivityOptions` |

**Returns:** `Promise<CanResolveActivityResult>`

**Since:** 0.1.0

______________________________________________________________________

### startActivity(...)

```
startActivity(options: StartActivityOptions) => Promise<StartActivityResult>
```

Launch an activity for the given intent.

The intent is started via the `startActivityForResult(...)` API so the result code and result data of the launched activity are returned once it finishes.

This is the power-user escape hatch for system screens and app integrations that no dedicated plugin covers. Prefer a typed plugin (such as [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) or [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/)) where one exists.

Only available on Android.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartActivityOptions` |

**Returns:** `Promise<StartActivityResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CanResolveActivityResult

| Prop             | Type      | Description                                                   | Since |
| ---------------- | --------- | ------------------------------------------------------------- | ----- |
| **`canResolve`** | `boolean` | Whether or not an activity exists that can handle the intent. | 0.1.0 |

#### StartActivityOptions

| Prop              | Type                        | Description                                                                                                                                                                                                                                            | Since        |
| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| **`action`**      | `string`                    | The action of the intent.                                                                                                                                                                                                                              | 0.1.0        |
| **`categories`**  | `string[]`                  | The categories to add to the intent.                                                                                                                                                                                                                   | 0.1.0        |
| **`className`**   | `string`                    | The fully qualified class name of the component to launch. Must be used together with the `packageName` property to create an explicit intent that targets a specific component.                                                                       | 0.1.0        |
| **`dataUri`**     | `string`                    | The data URI of the intent.                                                                                                                                                                                                                            | 0.1.0        |
| **`extras`**      | \`{ \[key: string\]: string | number                                                                                                                                                                                                                                                 | boolean; }\` |
| **`flags`**       | `number`                    | The flags to add to the intent. Multiple flags can be combined using the bitwise OR operator.                                                                                                                                                          | 0.1.0        |
| **`packageName`** | `string`                    | The package name of the component to launch. If used without the `className` property, the intent is restricted to the given package. If used together with the `className` property, an explicit intent that targets a specific component is created. | 0.1.0        |
| **`type`**        | `string`                    | The MIME type of the intent data.                                                                                                                                                                                                                      | 0.1.0        |

#### StartActivityResult

| Prop             | Type     | Description                                                                                                                                                                                                                        | Since                                           |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **`dataUri`**    | \`string | null\`                                                                                                                                                                                                                             | The data URI returned by the launched activity. |
| **`resultCode`** | `number` | The result code returned by the launched activity. The value is `-1` if the activity finished successfully (`RESULT_OK`), `0` if it was canceled (`RESULT_CANCELED`) or any other custom result code set by the launched activity. | 0.1.0                                           |

### Type Aliases

#### CanResolveActivityOptions

`StartActivityOptions`

## Common Intents

The following table lists a few common intents to get you started. See the [Android documentation](https://developer.android.com/reference/android/content/Intent) for the full list of actions, categories, extras and flags.

| Use case          | `action`                                        | `dataUri`                 | `type`       | `extras`                                          |
| ----------------- | ----------------------------------------------- | ------------------------- | ------------ | ------------------------------------------------- |
| Open a website    | `android.intent.action.VIEW`                    | `https://capawesome.io`   | –            | –                                                 |
| Open the dialer   | `android.intent.action.DIAL`                    | `tel:+12025550123`        | –            | –                                                 |
| Compose an email  | `android.intent.action.SENDTO`                  | `mailto:hi@example.com`   | –            | `{ 'android.intent.extra.SUBJECT': 'Hi' }`        |
| Share plain text  | `android.intent.action.SEND`                    | –                         | `text/plain` | `{ 'android.intent.extra.TEXT': 'Hello world!' }` |
| Open app settings | `android.settings.APPLICATION_DETAILS_SETTINGS` | `package:com.example.app` | –            | –                                                 |

This plugin is intended as a **last resort** for system screens and app integrations that no dedicated plugin covers. Prefer a typed plugin where one exists — for example [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) for system settings screens or [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/) for opening URLs and other apps.

## Package Visibility

On Android 11 (API level 30) and higher, [package visibility](https://developer.android.com/training/package-visibility) limits which other apps your app can interact with. This affects both `startActivity(...)` (an unresolvable intent rejects with the error code `ACTIVITY_NOT_FOUND`) and `canResolveActivity(...)` (which returns `false` for intents your app cannot see).

If you launch or resolve intents that target other apps, declare the intents you query in your app's `AndroidManifest.xml`. The plugin cannot predeclare arbitrary intents on your behalf.

```
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <queries>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="https" />
    </intent>
  </queries>
</manifest>
```

## FAQ

### How is this plugin different from other similar plugins?

It launches arbitrary Android intents — explicit or implicit — so you can open system screens or hand off to other apps even when no dedicated plugin covers them, and read the activity result back. You can attach primitive extras and intent flags, and resolve whether an activity can handle an intent before launching it, all through a fully typed API kept current with the latest Capacitor version. When a focused plugin already exists for your target, such as Settings Launcher or App Launcher, that is a fine choice; when you need full control over the raw intent, this plugin is built for it.

### Why does `startActivity` reject with the error code `ACTIVITY_NOT_FOUND`?

This happens when no activity exists that can handle the given intent. On Android 11 (API level 30) and higher, this can also be caused by [package visibility](#package-visibility), which limits which other apps your app can see. In that case, declare the intents you query in your app's `AndroidManifest.xml` using `<queries>` entries.

### Does this plugin work on iOS or Web?

No, intents are an Android-only concept, so this plugin has no iOS or Web implementation. On iOS and Web, all methods reject as unimplemented.

### When should I use this plugin instead of a dedicated plugin?

This plugin is intended as a last resort for system screens and app integrations that no dedicated plugin covers. Prefer a typed plugin where one exists, for example [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) for system settings screens or [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/) for opening URLs and other apps.

### Can I pass complex data as intent extras?

No, only primitive values (string, number and boolean) are supported as intent extras. Intent flags can be attached as well and multiple flags can be combined using the bitwise OR operator.

### How do I know whether the launched activity was successful?

The `startActivity(...)` method resolves with the result code returned by the launched activity once it finishes. The value is `-1` if the activity finished successfully (`RESULT_OK`), `0` if it was canceled (`RESULT_CANCELED`), or any other custom result code set by the launched activity.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/): Check if an app can be opened and open it.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens with a typed API.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-intent-launcher/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-intent-launcher/LICENSE).

# Capacitor Android SMS Retriever Plugin

Capacitor plugin for OTP autofill on Android via the SMS User Consent and Phone Number Hint APIs.

## Features

- 💬 **SMS User Consent**: Read an incoming verification SMS after a one-tap system consent dialog.
- 📞 **Phone Number Hint**: Prefill the user's phone number via the system bottom sheet.
- 🔒 **No SMS permissions**: Uses Play-policy-safe APIs that require no SMS permissions.
- 🤝 **Compatibility**: Works alongside the [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/), [SIM](https://capawesome.io/docs/sdks/capacitor/sim/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Android SMS Retriever plugin is typically used in phone number verification flows, for example:

- **OTP autofill**: Retrieve an incoming verification SMS after a one-tap system consent dialog and extract the one-time code, so the user doesn't have to type it manually.
- **Phone number prefill**: Prefill the phone number input field of your sign-up or login form via the system bottom sheet.
- **Play-policy-safe SMS verification**: Implement SMS-based verification without requesting any SMS permissions, using the SMS User Consent and Phone Number Hint APIs.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-android-sms-retriever` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-android-sms-retriever
npx cap sync
```

This plugin is only available on **Android**. On iOS and Web, all methods reject as unimplemented (see [iOS](#ios) below).

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$playServicesAuthVersion` version of `com.google.android.gms:play-services-auth` (default: `21.5.0`)
- `$playServicesAuthApiPhoneVersion` version of `com.google.android.gms:play-services-auth-api-phone` (default: `18.3.0`)

### iOS

This plugin has **no iOS implementation** and you don't need one. iOS already autofills one-time codes from incoming SMS messages in `WKWebView` when the input field uses `autocomplete="one-time-code"`:

```
<input autocomplete="one-time-code" />
```

All methods reject as unimplemented on iOS.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to prefill the user's phone number and retrieve a verification SMS.

### Prefill the user's phone number

Request the user's phone number via the Phone Number Hint API. A system bottom sheet is displayed that lets the user pick one of the phone numbers associated with the device, for example to prefill a phone number input field. Only available on Android:

```
import { AndroidSmsRetriever } from '@capawesome/capacitor-android-sms-retriever';

const requestPhoneNumber = async () => {
  const { phoneNumber } = await AndroidSmsRetriever.requestPhoneNumber();
  return phoneNumber;
};
```

### Retrieve a verification SMS

Retrieve an incoming verification SMS via the SMS User Consent API. A system consent dialog is displayed when a matching SMS is received, and the promise resolves with the full message text once the user consents, so your app can extract the one-time code itself (see [Extracting the One-Time Code](#extracting-the-one-time-code)). Only available on Android:

```
import { AndroidSmsRetriever } from '@capawesome/capacitor-android-sms-retriever';

const retrieveSms = async () => {
  const { message } = await AndroidSmsRetriever.retrieveSms();
  // Extract the one-time code from the message.
  const code = message.match(/\d{6}/)?.[0];
  return code;
};
```

## API

- [`requestPhoneNumber()`](#requestphonenumber)
- [`retrieveSms(...)`](#retrievesms)
- [Interfaces](#interfaces)

### requestPhoneNumber()

```
requestPhoneNumber() => Promise<RequestPhoneNumberResult>
```

Request the user's phone number via the Phone Number Hint API.

A system bottom sheet is displayed that lets the user pick one of the phone numbers associated with the device. The selected phone number is returned so it can be used to prefill a phone number input field.

Only available on Android.

**Returns:** `Promise<RequestPhoneNumberResult>`

**Since:** 0.1.0

______________________________________________________________________

### retrieveSms(...)

```
retrieveSms(options?: RetrieveSmsOptions | undefined) => Promise<RetrieveSmsResult>
```

Retrieve an incoming verification SMS via the SMS User Consent API.

A system consent dialog is displayed when a matching SMS is received. The promise resolves with the full message text once the user consents, so the app can extract the one-time code itself.

The underlying broadcast waits up to 5 minutes for a matching SMS. If no SMS is received within this time, the promise rejects with the error code `TIMEOUT`.

Only available on Android.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `RetrieveSmsOptions` |

**Returns:** `Promise<RetrieveSmsResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### RequestPhoneNumberResult

| Prop              | Type     | Description                            | Since |
| ----------------- | -------- | -------------------------------------- | ----- |
| **`phoneNumber`** | `string` | The phone number selected by the user. | 0.1.0 |

#### RetrieveSmsResult

| Prop          | Type     | Description                                                                                                           | Since |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`message`** | `string` | The full text of the retrieved SMS message. The app is responsible for extracting the one-time code from the message. | 0.1.0 |

#### RetrieveSmsOptions

| Prop                    | Type     | Description                                                                                                           | Since |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`senderPhoneNumber`** | `string` | The phone number of the sender to filter incoming messages by. If not provided, the SMS from any sender is retrieved. | 0.1.0 |

## Extracting the One-Time Code

The `retrieveSms(...)` method resolves with the full text of the incoming SMS message. Your app is responsible for extracting the one-time code from the message, for example with a regular expression:

```
const { message } = await AndroidSmsRetriever.retrieveSms();
const code = message.match(/\d{6}/)?.[0];
```

For the SMS User Consent API to detect a message, the SMS must:

- contain a one-time code that the user sends back to your server to complete the verification,
- be no longer than 140 bytes,
- not originate from a phone number in the user's contacts.

The underlying broadcast waits up to 5 minutes for a matching SMS. If no message is received within this time, the promise rejects with the error code `TIMEOUT`.

## FAQ

### How is this plugin different from other similar plugins?

It implements OTP autofill on Android through the SMS User Consent and Phone Number Hint APIs, so you can read a verification SMS and prefill the user's phone number without requesting any SMS permissions and while staying within Google Play policy. It's a focused, fully typed API that handles the system consent dialog and bottom sheet for you, and it's actively maintained against the latest Capacitor and Android versions. On iOS you don't need it at all — the WebView already autofills one-time codes — and the README explains exactly how.

### Does this plugin require any SMS permissions?

No, the plugin uses the SMS User Consent and Phone Number Hint APIs, which are Play-policy-safe and require no SMS permissions. Instead of reading SMS messages silently, the user explicitly consents via a one-tap system dialog before your app receives the message.

### Does this plugin work on iOS or Web?

No, this plugin only provides an Android implementation and you don't need one on iOS. iOS already autofills one-time codes from incoming SMS messages in `WKWebView` when the input field uses `autocomplete="one-time-code"`. On iOS and Web, all methods reject as unimplemented.

### Why does `retrieveSms` reject with the error code `TIMEOUT`?

The underlying broadcast waits up to 5 minutes for a matching SMS. If no matching message is received within this time, the promise rejects with the error code `TIMEOUT`. Make sure the SMS is sent while the broadcast is active and meets the requirements of the SMS User Consent API.

### Why is my SMS message not detected?

For the SMS User Consent API to detect a message, the SMS must contain a one-time code that the user sends back to your server to complete the verification, be no longer than 140 bytes, and not originate from a phone number in the user's contacts. See [Extracting the One-Time Code](#extracting-the-one-time-code) for more information.

### Can I filter incoming messages by sender?

Yes, you can pass the `senderPhoneNumber` option to the `retrieveSms(...)` method to only retrieve messages from a specific sender. If not provided, the SMS from any sender is retrieved.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/): Save passwords to the platform credential store.
- [SIM](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information.
- [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-sms-retriever/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-sms-retriever/LICENSE).

# Capacitor App Icon Plugin

Capacitor plugin to change the app icon at runtime.

## Features

- 🎨 **Alternate icons**: Switch the home-screen icon between the icons your app declares.
- 🔍 **Current icon**: Read the name of the icon that is currently in use.
- 🔄 **Reset**: Restore the default icon at any time.
- 🤝 **Compatibility**: Works alongside the [App Shortcuts](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/) and [Badge](https://capawesome.io/docs/sdks/capacitor/badge/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Icon plugin is typically used to personalize or refresh the app's appearance on the home screen, for example:

- **Seasonal campaigns**: Switch to a themed icon for events like Christmas and restore the default icon afterwards.
- **Premium personalization**: Let paying users choose their favorite icon from a set of alternate icons.
- **In-app icon picker**: Build a settings screen that lists all icons and highlights the one currently in use.
- **Brand updates**: Roll out a new logo as an alternate icon and switch to it at runtime.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-icon` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-icon
npx cap sync
```

This plugin cannot add icons dynamically. Every icon you want to switch to must be **declared by the app beforehand**. The following sections describe how to declare alternate icons on each platform.

### Android

On Android, each alternate icon is declared as an [`<activity-alias>`](https://developer.android.com/guide/topics/manifest/activity-alias-element) that points at the launcher activity. The plugin enables the requested alias and disables the others.

Open your `AndroidManifest.xml` and remove the launcher `<intent-filter>` from your `.MainActivity`. Then add one `<activity-alias>` for the default icon and one for each alternate icon. Exactly one alias must be `android:enabled="true"` (the default icon); all others must be `android:enabled="false"`.

```
<!-- Remove the <intent-filter> from the MainActivity. -->
<activity
    android:name=".MainActivity"
    android:exported="true"
    ... />

<!-- The default icon (enabled). -->
<activity-alias
    android:name=".AppIconDefault"
    android:enabled="true"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

<!-- An alternate icon (disabled). -->
<activity-alias
    android:name=".Christmas"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_christmas"
    android:roundIcon="@mipmap/ic_launcher_christmas_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

<!-- Another alternate icon (disabled). -->
<activity-alias
    android:name=".Halloween"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_halloween"
    android:roundIcon="@mipmap/ic_launcher_halloween_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>
```

The icon name passed to `setIcon(...)` is the alias name **without the leading dot** (e.g. `Christmas`). Add the referenced icon resources (e.g. `@mipmap/ic_launcher_christmas`) to your `res/mipmap-*` folders.

> [!NOTE] The behavior after a change depends on the launcher. Some launchers apply the new icon only after the app's task is closed, and a few kill the app despite the plugin requesting otherwise. Shortcuts that were pinned to a now-disabled alias may stop working.

### iOS

On iOS, alternate icons are declared as additional app icon sets in the asset catalog. Add one icon set per alternate icon (e.g. `Christmas` and `Halloween`) next to your primary `AppIcon` in `Assets.xcassets` and register the names (space-separated) in the build settings of your app target:

```
ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES = "Christmas Halloween";
ASSETCATALOG_COMPILER_INCLUDE_ALL_APPICON_ASSETS = YES;
```

In Xcode, these settings are called **Alternate App Icon Sets** and **Include All App Icon Assets** in the *Asset Catalog Compiler* section of the build settings.

The icon name passed to `setIcon(...)` is the name of the icon set (e.g. `Christmas`), case-sensitive. The primary icon (`AppIcon`) is restored with `resetIcon(...)`.

> [!WARNING] Do **not** give an alternate icon set a name that starts with `AppIcon` (e.g. `AppIconChristmas`). In our testing on physical devices running iOS 26, alternate icons whose name shares the primary icon set's `AppIcon` prefix are not rendered on the home screen: `setIcon(...)` succeeds, but the system displays a blank placeholder icon instead of the alternate icon. The iOS Simulator is not affected, so make sure to test on a real device. This is an undocumented iOS behavior; using names without the `AppIcon` prefix is safe on all iOS versions.
>
> [!NOTE] The system shows a user-visible alert every time the icon changes, and the icon cannot be changed while the app is in the background.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check for alternate icon support, read the current icon, set an alternate icon, and reset to the default icon.

### Check if changing the app icon is supported

Use `isAvailable()` to check whether the current device supports alternate icons. On Android, this always resolves to `true`; on iOS, it resolves to the value of `supportsAlternateIcons`. Only available on Android and iOS:

```
import { AppIcon } from '@capawesome/capacitor-app-icon';

const isAvailable = async () => {
  const { available } = await AppIcon.isAvailable();
  return available;
};
```

### Get the current icon

Read the name of the icon that is currently in use, for example to highlight it in an icon picker. Returns `null` if the default icon is in use. Only available on Android and iOS:

```
import { AppIcon } from '@capawesome/capacitor-app-icon';

const getCurrentIcon = async () => {
  const { icon } = await AppIcon.getCurrentIcon();
  return icon;
};
```

### Set an alternate icon

Change the app icon to an alternate icon that your app has declared beforehand (see [Installation](#installation)). Only available on Android and iOS:

```
import { AppIcon } from '@capawesome/capacitor-app-icon';

const setIcon = async () => {
  await AppIcon.setIcon({ icon: 'Christmas' });
};
```

### Reset to the default icon

Restore the default app icon at any time. Only available on Android and iOS:

```
import { AppIcon } from '@capawesome/capacitor-app-icon';

const resetIcon = async () => {
  await AppIcon.resetIcon();
};
```

## API

- [`getCurrentIcon()`](#getcurrenticon)
- [`isAvailable()`](#isavailable)
- [`resetIcon()`](#reseticon)
- [`setIcon(...)`](#seticon)
- [Interfaces](#interfaces)

### getCurrentIcon()

```
getCurrentIcon() => Promise<GetCurrentIconResult>
```

Get the name of the icon that is currently in use.

Returns `null` if the default icon is in use.

Only available on Android and iOS.

**Returns:** `Promise<GetCurrentIconResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if changing the app icon is supported on the current device.

On Android, this always resolves to `true`. On iOS, this resolves to the value of `supportsAlternateIcons`.

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### resetIcon()

```
resetIcon() => Promise<void>
```

Restore the default app icon.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### setIcon(...)

```
setIcon(options: SetIconOptions) => Promise<void>
```

Change the app icon to the alternate icon with the given name.

The icon must be declared by the app beforehand. See the setup instructions for [Android](https://capawesome.io/docs/sdks/capacitor/app-icon/#android) and [iOS](https://capawesome.io/docs/sdks/capacitor/app-icon/#ios) for more information.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `SetIconOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetCurrentIconResult

| Prop       | Type     | Description | Since                                                                                        |
| ---------- | -------- | ----------- | -------------------------------------------------------------------------------------------- |
| **`icon`** | \`string | null\`      | The name of the icon that is currently in use. Returns `null` if the default icon is in use. |

#### IsAvailableResult

| Prop            | Type      | Description                                                              | Since |
| --------------- | --------- | ------------------------------------------------------------------------ | ----- |
| **`available`** | `boolean` | Whether or not changing the app icon is supported on the current device. | 0.1.0 |

#### SetIconOptions

| Prop       | Type     | Description                                                                                                                                                                                                 | Since |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`icon`** | `string` | The name of the alternate icon to use. On Android, this is the name of the `&lt;activity-alias&gt;` (without the leading dot). On iOS, this is the name of the alternate app icon set in the asset catalog. | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It changes the app icon at runtime on both Android and iOS through one fully typed API — switching to a declared alternate icon, reading the icon currently in use, resetting to the default, and checking whether the device supports alternate icons. It documents the platform realities honestly, from Android's launcher-dependent behavior to the system alert iOS shows on every change, so there are no surprises in production. The plugin is actively maintained against the latest Capacitor and OS versions.

### Can I add new app icons at runtime?

No, this plugin cannot add icons dynamically. Every icon you want to switch to must be declared by the app beforehand, as an `<activity-alias>` in the `AndroidManifest.xml` on Android and as an alternate app icon set in the asset catalog on iOS. See the [Installation](#installation) section for detailed setup instructions.

### What icon name do I pass to `setIcon`?

On Android, it is the name of the `<activity-alias>` without the leading dot (e.g. `Christmas`). On iOS, it is the name of the alternate app icon set in the asset catalog.

### Why is the new icon not applied immediately on Android?

The behavior after a change depends on the launcher. Some launchers apply the new icon only after the app's task is closed, and a few even kill the app despite the plugin requesting otherwise. Also note that shortcuts pinned to a now-disabled alias may stop working.

### Why does iOS show an alert when the icon changes?

The system shows a user-visible alert every time the icon changes. This is standard iOS behavior and cannot be suppressed. Also note that the icon cannot be changed while the app is in the background.

### How do I know if the device supports alternate icons?

Call `isAvailable()` before offering an icon picker. On Android, it always resolves to `true`. On iOS, it resolves to the value of `supportsAlternateIcons`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Shortcuts](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/): Manage app shortcuts and quick actions on the home screen.
- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist your users with native app updates.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-icon/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-icon/LICENSE).

# Capacitor App Integrity Plugin

Capacitor plugin to verify app and device integrity using the Play Integrity API (Android) and App Attest (iOS).

## Features

- 🤖 **Play Integrity**: Request standard and classic integrity tokens from the Play Integrity API on Android.
- 🍏 **App Attest**: Generate hardware-backed keys, attest them and generate assertions with App Attest on iOS.
- 🛡️ **Server-verifiable**: Tokens and assertions are verified on your backend via Google and Apple, so they cannot be spoofed on the device.
- 🤝 **Compatibility**: Works alongside the [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/) plugin for additional client-side checks.
- 📦 **SPM**: Supports Swift Package Manager and CocoaPods for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Integrity plugin is typically used to protect your backend from requests that do not originate from your genuine, unmodified app, for example:

- **API protection**: Attach integrity tokens or assertions to requests to sensitive endpoints so your server can reject tampered clients.
- **Fraud prevention**: Verify high-value actions such as payments or account changes with a classic integrity request or an App Attest assertion.
- **Account security**: Protect login and registration flows against bots and automated abuse.
- **Gated content**: Grant access to protected resources only after your server has verified the integrity verdict.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-integrity` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-integrity
npx cap sync
```

### Android

The Play Integrity API must be set up in the Google Play Console before you can request integrity tokens. Follow the [official setup instructions](https://developer.android.com/google/play/integrity/setup) to link a Google Cloud project to your app. You need the **Google Cloud project number** of the linked project for the standard request flow.

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$playIntegrityVersion` version of `com.google.android.play:integrity` (default: `1.6.0`)

### iOS

App Attest requires the **App Attest capability**. Add it to your app in Xcode under **Signing & Capabilities** or add the following entitlement to your `.entitlements` file:

```
<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>development</string>
```

Use the value `development` to attest against Apple's sandbox servers during development and `production` for App Store builds. Note that App Attest is not supported on simulators, so you need a real device for testing.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check for integrity attestation support, request an integrity token on Android, attest a key on iOS, and generate an assertion on iOS.

### Check if integrity attestation is available

Use `isAvailable()` before requesting tokens or attestations. On Android, this checks whether Google Play Services is available; on iOS, it checks whether the App Attest service is supported (it is not supported on simulators):

```
import { AppIntegrity } from '@capawesome/capacitor-app-integrity';

const isAvailable = async () => {
  const { available } = await AppIntegrity.isAvailable();
  return available;
};
```

### Request an integrity token on Android

For the recommended standard request flow, prepare the integrity token provider once (for example at app start) with your Google Cloud project number, since the preparation can take several seconds. Then request tokens with a `requestHash`. For infrequent, high-value actions you can use the classic request flow with a `nonce` instead. Only available on Android:

```
import { AppIntegrity } from '@capawesome/capacitor-app-integrity';
import { Capacitor } from '@capacitor/core';

const prepareIntegrityToken = async () => {
  // Only available on Android
  await AppIntegrity.prepareIntegrityToken({
    cloudProjectNumber: 123456789012,
  });
};

const requestIntegrityToken = async () => {
  // Only available on Android
  if (Capacitor.getPlatform() === 'android') {
    // Standard request (recommended, requires a prior call to `prepareIntegrityToken(...)`)
    const { token } = await AppIntegrity.requestIntegrityToken({
      requestHash: '2cp24z...',
    });
    // Classic request
    const { token: classicToken } = await AppIntegrity.requestIntegrityToken({
      nonce: 'R2Rra24fVm5xa2Mg',
    });
    // Send the token to your server for verification
  }
};
```

### Attest a key on iOS

Generate a hardware-backed key pair and attest it with a one-time challenge received from your server. The attestation object must be sent to your server for verification with Apple. Only available on iOS:

```
import { AppIntegrity } from '@capawesome/capacitor-app-integrity';
import { Capacitor } from '@capacitor/core';

const attestKey = async () => {
  // Only available on iOS
  if (Capacitor.getPlatform() === 'ios') {
    // 1. Generate a new key pair and store the key identifier
    const { keyId } = await AppIntegrity.generateKey();
    // 2. Attest the key with a one-time challenge received from your server
    const { attestationObject } = await AppIntegrity.attestKey({
      keyId,
      challenge: 'dGhpc2lzYWNoYWxsZW5nZQ==',
    });
    // 3. Send the attestation object to your server for verification
  }
};
```

### Generate an assertion on iOS

Once a key is attested, sign client data (usually a JSON payload that includes a one-time challenge from your server) to prove that a request comes from your genuine app. Only available on iOS:

```
import { AppIntegrity } from '@capawesome/capacitor-app-integrity';
import { Capacitor } from '@capacitor/core';

const generateAssertion = async () => {
  // Only available on iOS
  if (Capacitor.getPlatform() === 'ios') {
    const { assertion } = await AppIntegrity.generateAssertion({
      keyId: 'Kh0DIEwVJTDJUyIRZ4M9BvJn/i4RSSGDkFvUZOaSm5g=',
      clientData: 'eyJjaGFsbGVuZ2UiOiJkR2hwYzJsellXTm9ZV3hzWlc1blpRPT0ifQ==',
    });
    // Send the assertion to your server for verification
  }
};
```

## API

- [`attestKey(...)`](#attestkey)
- [`generateAssertion(...)`](#generateassertion)
- [`generateKey()`](#generatekey)
- [`isAvailable()`](#isavailable)
- [`prepareIntegrityToken(...)`](#prepareintegritytoken)
- [`requestIntegrityToken(...)`](#requestintegritytoken)
- [Interfaces](#interfaces)

### attestKey(...)

```
attestKey(options: AttestKeyOptions) => Promise<AttestKeyResult>
```

Attest a key generated with `generateKey()` using Apple's App Attest service.

The returned attestation object must be sent to your server, which verifies it with Apple and stores the key identifier for future assertions.

Only available on iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AttestKeyOptions` |

**Returns:** `Promise<AttestKeyResult>`

**Since:** 0.1.0

______________________________________________________________________

### generateAssertion(...)

```
generateAssertion(options: GenerateAssertionOptions) => Promise<GenerateAssertionResult>
```

Generate an assertion for the given client data using an attested key.

The returned assertion must be sent to your server along with the client data, where it is verified using the previously stored key identifier.

Only available on iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `GenerateAssertionOptions` |

**Returns:** `Promise<GenerateAssertionResult>`

**Since:** 0.1.0

______________________________________________________________________

### generateKey()

```
generateKey() => Promise<GenerateKeyResult>
```

Generate a new App Attest key pair.

The private key is stored in the Secure Enclave. Store the returned key identifier in your app to attest the key and generate assertions later.

Only available on iOS.

**Returns:** `Promise<GenerateKeyResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether app integrity attestation is available on this device.

On Android, this checks whether Google Play Services is available. On iOS, this checks whether the App Attest service is supported. On iOS, the App Attest service is not supported on simulators.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### prepareIntegrityToken(...)

```
prepareIntegrityToken(options: PrepareIntegrityTokenOptions) => Promise<void>
```

Prepare the integrity token provider for standard integrity token requests.

Call this method once, for example at app start, before calling `requestIntegrityToken(...)` with a request hash. The preparation can take several seconds, so it should be done well ahead of the first request.

Only available on Android.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `PrepareIntegrityTokenOptions` |

**Since:** 0.1.0

______________________________________________________________________

### requestIntegrityToken(...)

```
requestIntegrityToken(options: RequestIntegrityTokenOptions) => Promise<RequestIntegrityTokenResult>
```

Request an integrity token from the Play Integrity API.

Provide a `requestHash` for a standard request (recommended, requires a prior call to `prepareIntegrityToken(...)`) or a `nonce` for a classic request.

The returned token must be sent to your server, which decrypts and verifies it via Google's servers.

Only available on Android.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `RequestIntegrityTokenOptions` |

**Returns:** `Promise<RequestIntegrityTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AttestKeyResult

| Prop                    | Type     | Description                                                                                               | Since |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`attestationObject`** | `string` | The attestation object, encoded as a base64 string. Send this to your server for verification with Apple. | 0.1.0 |

#### AttestKeyOptions

| Prop            | Type     | Description                                                                                                                                                                     | Since |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`challenge`** | `string` | The one-time challenge received from your server, encoded as a base64 string. The challenge is hashed with SHA-256 on the device before it is passed to the App Attest service. | 0.1.0 |
| **`keyId`**     | `string` | The identifier of the key to attest, as returned by `generateKey()`.                                                                                                            | 0.1.0 |

#### GenerateAssertionResult

| Prop            | Type     | Description                                                                                  | Since |
| --------------- | -------- | -------------------------------------------------------------------------------------------- | ----- |
| **`assertion`** | `string` | The assertion object, encoded as a base64 string. Send this to your server for verification. | 0.1.0 |

#### GenerateAssertionOptions

| Prop             | Type     | Description                                                                                                                                                                                                                                           | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`clientData`** | `string` | The client data to sign, encoded as a base64 string. This is usually a JSON payload that includes a one-time challenge received from your server. The client data is hashed with SHA-256 on the device before it is passed to the App Attest service. | 0.1.0 |
| **`keyId`**      | `string` | The identifier of an attested key, as returned by `generateKey()`.                                                                                                                                                                                    | 0.1.0 |

#### GenerateKeyResult

| Prop        | Type     | Description                               | Since |
| ----------- | -------- | ----------------------------------------- | ----- |
| **`keyId`** | `string` | The identifier of the generated key pair. | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                                    | Since |
| --------------- | --------- | -------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether app integrity attestation is available on this device. | 0.1.0 |

#### PrepareIntegrityTokenOptions

| Prop                     | Type     | Description                                                                                           | Since |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------- | ----- |
| **`cloudProjectNumber`** | `number` | The Google Cloud project number of the project that is linked to your Play Console developer account. | 0.1.0 |

#### RequestIntegrityTokenResult

| Prop        | Type     | Description                                                                                         | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`token`** | `string` | The integrity token. Send this to your server, which decrypts and verifies it via Google's servers. | 0.1.0 |

#### RequestIntegrityTokenOptions

| Prop                     | Type     | Description                                                                                                                                                                                             | Since |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`cloudProjectNumber`** | `number` | The Google Cloud project number of the project that is linked to your Play Console developer account. Only used for classic requests. It is required if your app is distributed outside of Google Play. | 0.1.0 |
| **`nonce`**              | `string` | The one-time nonce for a classic request, encoded as a base64 web-safe no-wrap string. Provide either `nonce` or `requestHash`.                                                                         | 0.1.0 |
| **`requestHash`**        | `string` | The request hash for a standard request. Requires a prior call to `prepareIntegrityToken(...)`. Provide either `nonce` or `requestHash`.                                                                | 0.1.0 |

## How Verification Works

This plugin only provides the **client-side** part of the attestation flow. The returned tokens, attestation objects, and assertions are opaque to your app and **must** be verified on your own server. Never make security decisions based on the client-side result alone.

The typical flow looks like this:

1. Your app requests a one-time challenge (or nonce) from your server.
1. Your app calls this plugin to obtain an integrity token (Android) or an attestation object/assertion (iOS) that is bound to the challenge.
1. Your app sends the result to your server.
1. Your server verifies the result:
1. **Android**: Decrypt and verify the integrity token via the [Play Integrity API](https://developer.android.com/google/play/integrity/verdicts) and evaluate the verdicts.
1. **iOS**: Validate the attestation object or assertion as described in [Validating Apps That Connect to Your Server](https://developer.apple.com/documentation/devicecheck/validating-apps-that-connect-to-your-server).
1. Your server grants or denies access based on the verification result.

On Android, Google recommends the **standard request** flow (`prepareIntegrityToken(...)` + `requestIntegrityToken({ requestHash })`) for frequent integrity checks. Use the **classic request** flow (`requestIntegrityToken({ nonce })`) only for infrequent, high-value actions.

## FAQ

### How is this plugin different from other similar plugins?

It brings both platforms' hardware-backed attestation under one fully typed API — the Play Integrity API on Android with standard and classic requests, and App Attest on iOS with key generation, attestation, and assertions. Every result is meant to be verified server-side via Google and Apple, so integrity decisions can't be spoofed on the device, and an `isAvailable()` check lets you adapt before you request. If client-side root and jailbreak signals are all you need, a lighter check may suffice; if you want tokens and assertions your backend can actually trust, this plugin is built for exactly that.

### Do I need my own server to use this plugin?

Yes. This plugin only provides the client-side part of the attestation flow. The returned tokens, attestation objects, and assertions are opaque to your app and must be decrypted and verified on your own server via Google (Android) or Apple (iOS). Never make security decisions based on the client-side result alone. See the [How Verification Works](#how-verification-works) section for the typical flow.

### What is the difference between a standard and a classic request on Android?

A standard request is the flow recommended by Google for frequent integrity checks: it requires a prior call to `prepareIntegrityToken(...)` and passes a `requestHash` to `requestIntegrityToken(...)`. A classic request passes a `nonce` instead, requires no preparation, and should only be used for infrequent, high-value actions.

### Why does `isAvailable` return `false` on the iOS Simulator?

The App Attest service is not supported on simulators, so you need a real device for testing. On Android, `isAvailable()` checks whether Google Play Services is available.

### What do I need to set up before requesting integrity tokens on Android?

The Play Integrity API must be set up in the Google Play Console by linking a Google Cloud project to your app. You need the Google Cloud project number of the linked project for the standard request flow. See the [Installation](#installation) section for more information.

### How is this plugin different from the Root Detection plugin?

The [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/) plugin performs client-side checks for rooted and jailbroken devices, which can be helpful but can also be bypassed on a compromised device. The App Integrity plugin provides server-verifiable tokens and assertions that are verified via Google and Apple, so they cannot be spoofed on the device. The two plugins work well together as complementary layers.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face or fingerprint recognition.
- [Google Play Services](https://capawesome.io/docs/sdks/capacitor/google-play-services/): Check whether Google Play Services is available on the device and prompt the user to install or update it.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices with client-side checks.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-integrity/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-integrity/LICENSE).

# Capacitor App Language Plugin

Capacitor plugin to manage the app's own language override, independent of the device language.

## Features

- 🌐 **Language override**: Set the app's language independently of the device language (Android).
- 🔎 **Read language**: Read the app's current language override.
- ♻️ **Reset**: Clear the override so the app follows the device language again (Android).
- ⚙️ **Settings**: Deep-link to the app's system settings page where the user can change the app language.
- 🤝 **Compatibility**: Works alongside the [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugin, which reads the user's localization preferences.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Language plugin is typically used whenever an app offers its own language selection, for example:

- **In-app language switcher**: Let users pick the app language from a settings screen instead of changing the device language (Android).
- **Consistent native dialogs**: Make sure natively rendered strings like permission dialogs and notifications match the language of your web UI.
- **Settings deep link**: Guide iOS users to the app's system settings page, where they can change the app language.
- **System default option**: Offer a "system default" entry that clears the override so the app follows the device language again (Android).

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-language` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-language
npx cap sync
```

This plugin only affects **natively rendered** strings (e.g. permission dialogs, notifications, or plugin-presented sheets). The language of your web UI should be handled by your app's i18n library.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxAppCompatVersion` version of `androidx.appcompat:appcompat` (default: `1.7.1`)

#### Locale Configuration

To integrate the app language into the system settings (Android 13+), declare the supported locales in a `res/xml/locales_config.xml` file and reference it from the `<application>` tag in your `AndroidManifest.xml`:

```
<!-- res/xml/locales_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="en" />
    <locale android:name="de" />
</locale-config>
```

```
<application
    ...
    android:localeConfig="@xml/locales_config">
```

To persist the selected language across app restarts on Android 12 and below, add the following `<service>` inside the `<application>` tag of your `AndroidManifest.xml`:

```
<service
    android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
    android:enabled="false"
    android:exported="false">
    <meta-data
        android:name="autoStoreLocales"
        android:value="true" />
</service>
```

> [!NOTE] Setting the language recreates the current activity, which reloads the web view.

### iOS

On iOS, the app language can only be changed by the **user** in the system settings. The `setLanguage(...)` and `resetLanguage(...)` methods are therefore not available. Use `openSettings(...)` to deep-link the user to the app's settings page.

The per-app language row is only shown in the system settings if the app bundle provides **more than one** localization. Declare the supported localizations in the `Info.plist` file of your app:

```
<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>de</string>
</array>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get, set, and reset the app language override and open the app's settings page.

### Get the current language override

Read the BCP 47 language tag of the app's current language override. Returns `null` if no override is set and the app follows the device language:

```
import { AppLanguage } from '@capawesome/capacitor-app-language';

const getLanguage = async () => {
  const { languageTag } = await AppLanguage.getLanguage();
  return languageTag;
};
```

### Set the app language

Set the app's language override, independent of the device language. Note that this recreates the current activity, which reloads the web view. Only available on Android:

```
import { AppLanguage } from '@capawesome/capacitor-app-language';

const setLanguage = async () => {
  await AppLanguage.setLanguage({ languageTag: 'de-DE' });
};
```

### Reset the language override

Clear the override so the app follows the device language again. Only available on Android:

```
import { AppLanguage } from '@capawesome/capacitor-app-language';

const resetLanguage = async () => {
  await AppLanguage.resetLanguage();
};
```

### Open the app's settings page

Deep-link the user to the app's page in the system settings. On iOS, this is where the user can change the app language:

```
import { AppLanguage } from '@capawesome/capacitor-app-language';

const openSettings = async () => {
  await AppLanguage.openSettings();
};
```

## API

- [`getLanguage()`](#getlanguage)
- [`openSettings()`](#opensettings)
- [`resetLanguage()`](#resetlanguage)
- [`setLanguage(...)`](#setlanguage)
- [Interfaces](#interfaces)

### getLanguage()

```
getLanguage() => Promise<GetLanguageResult>
```

Get the app's current language override.

The language override is independent of the device language and only affects natively rendered strings (e.g. permission dialogs).

**Returns:** `Promise<GetLanguageResult>`

**Since:** 0.1.0

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the app's settings page in the system settings.

On iOS, this is where the user can change the app's language (the language row is only shown if the app bundle provides more than one localization).

**Since:** 0.1.0

______________________________________________________________________

### resetLanguage()

```
resetLanguage() => Promise<void>
```

Reset the app's language override so the app follows the device language again.

Resetting the language recreates the current activity, which reloads the web view.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### setLanguage(...)

```
setLanguage(options: SetLanguageOptions) => Promise<void>
```

Set the app's language override.

Setting the language recreates the current activity, which reloads the web view.

On iOS, the language can only be changed by the user in the system settings (see the `openSettings(...)` method).

Only available on Android.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetLanguageOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetLanguageResult

| Prop              | Type     | Description | Since                                                                                                                                 |
| ----------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **`languageTag`** | \`string | null\`      | The BCP 47 language tag of the app's language override. Returns `null` if no override is set and the app follows the device language. |

#### SetLanguageOptions

| Prop              | Type     | Description                                                    | Since |
| ----------------- | -------- | -------------------------------------------------------------- | ----- |
| **`languageTag`** | `string` | The BCP 47 language tag to set as the app's language override. | 0.1.0 |

## Platform Behavior

Setting the app language programmatically is only supported on Android. On iOS, the language can only be changed by the user in the system settings.

| Method             | Android | iOS              | Web              |
| ------------------ | ------- | ---------------- | ---------------- |
| `getLanguage()`    | ✅      | ✅               | ❌ Unimplemented |
| `setLanguage(...)` | ✅      | ❌ Unimplemented | ❌ Unimplemented |
| `resetLanguage()`  | ✅      | ❌ Unimplemented | ❌ Unimplemented |
| `openSettings()`   | ✅      | ✅               | ❌ Unimplemented |

## FAQ

### Why can't I set the app language programmatically on iOS?

On iOS, the app language can only be changed by the user in the system settings, so the `setLanguage(...)` and `resetLanguage(...)` methods are not available there. Use `openSettings()` to deep-link the user to the app's settings page, where the language can be changed.

### Does this plugin translate my web UI?

No. The language override only affects natively rendered strings, such as permission dialogs, notifications, or plugin-presented sheets. The language of your web UI should be handled by your app's i18n library.

### Why is the language row not shown in the iOS system settings?

The per-app language row only appears if the app bundle provides more than one localization. Declare the supported localizations under the `CFBundleLocalizations` key in your app's `Info.plist`, as described in the [Installation](#installation) section.

### Why does my app reload after calling `setLanguage`?

Setting or resetting the language recreates the current activity on Android, which reloads the web view. This is expected behavior and cannot be avoided.

### How does the selected language persist across app restarts on Android?

On Android 13 and above, the override is integrated with the system settings via a `locales_config.xml` file. On Android 12 and below, you need to add the `AppLocalesMetadataHolderService` service to your `AndroidManifest.xml` to persist the selected language, as described in the [Installation](#installation) section.

### How is this plugin different from the Localization plugin?

The [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugin reads the user's localization preferences, such as preferred locales, time zone, and regional formatting settings. The App Language plugin manages the app's own language override, independent of the device language. The two plugins work well together.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Localization](https://capawesome.io/docs/sdks/capacitor/localization/): Read the user's localization preferences, such as preferred locales, time zone, and regional formatting settings.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-language/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-language/LICENSE).

# Capacitor App Launcher Plugin

Capacitor plugin to check if an app can be opened and to open it.

## Features

- 🔗 **Open apps**: Open another app by its URL scheme or package name.
- ✅ **Availability**: Check whether an app can be opened before trying to open it.
- 🤖 **Package names**: Check and open apps by their package name on Android.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/) and [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Launcher plugin is typically used to hand the user over to another app, for example:

- **App-to-app navigation**: Open a companion or partner app directly from your app via its URL scheme or package name.
- **Graceful fallbacks**: Check whether an app can be opened first and show an alternative if it is not installed.
- **Composing emails**: Open the user's mail app with a `mailto:` URL.
- **Launching Android apps by package name**: Open a specific app such as Gmail (`com.google.android.gm`) on Android.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-launcher` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-launcher
npx cap sync
```

### Android

Starting with Android 11 (API level 30), apps must declare the packages and URL schemes they want to check or open in the [`<queries>`](https://developer.android.com/training/package-visibility) element of their `AndroidManifest.xml`.

**If you do not add the corresponding `<queries>` entries, `canOpenUrl(...)` always resolves with `value: false` and `openUrl(...)` may resolve with `completed: false`.**

Add an entry for **every** package name and URL scheme you pass to the plugin. For example, to check and open the Gmail app (package name `com.google.android.gm`) and any `mailto:` URL, add the following to your `android/app/src/main/AndroidManifest.xml` before or after the `application` tag:

```
<queries>
    <!-- Required to check and open a specific package name. -->
    <package android:name="com.google.android.gm" />
    <!-- Required to check and open a specific URL scheme. -->
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="mailto" />
    </intent>
</queries>
```

### iOS

On iOS, every URL scheme you want to check with `canOpenUrl(...)` must be declared in the [`LSApplicationQueriesSchemes`](https://developer.apple.com/documentation/bundleresources/information_property_list/lsapplicationqueriesschemes) key of your app's `Info.plist`.

**If you do not add the corresponding entries, `canOpenUrl(...)` always resolves with `value: false`.**

Add an entry for **every** URL scheme you pass to the plugin. For example, to check any `mailto:` URL, add the following to your `ios/App/App/Info.plist`:

```
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>mailto</string>
</array>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether an app can be opened and open another app.

### Check if an app can be opened

Check whether an app can be opened before trying to open it. On iOS, the URL must be a URL scheme (e.g. `mailto:`); on Android, it can be a URL scheme or a package name (e.g. `com.google.android.gm`). Remember to declare every scheme and package name you check (see [Installation](#installation)), otherwise this method always resolves with `value: false`:

```
import { AppLauncher } from '@capawesome/capacitor-app-launcher';

const canOpenUrl = async () => {
  const { value } = await AppLauncher.canOpenUrl({ url: 'mailto:' });
  return value;
};
```

### Open an app

Open another app with the given URL. On Android, the URL can also be a package name. The result tells you whether the app was opened successfully:

```
import { AppLauncher } from '@capawesome/capacitor-app-launcher';

const openUrl = async () => {
  const { completed } = await AppLauncher.openUrl({ url: 'mailto:' });
  return completed;
};
```

## API

- [`canOpenUrl(...)`](#canopenurl)
- [`openUrl(...)`](#openurl)
- [Interfaces](#interfaces)

### canOpenUrl(...)

```
canOpenUrl(options: CanOpenUrlOptions) => Promise<CanOpenUrlResult>
```

Check if an app can be opened with the given URL.

On **iOS**, every URL scheme you want to check must be declared in the `LSApplicationQueriesSchemes` key of your app's `Info.plist`. Otherwise this method always resolves with `value: false`.

On **Android**, every package name or URL scheme you want to check must be declared in the `&lt;queries&gt;` element of your app's `AndroidManifest.xml`. Otherwise this method always resolves with `value: false`.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `CanOpenUrlOptions` |

**Returns:** `Promise<CanOpenUrlResult>`

**Since:** 0.1.0

______________________________________________________________________

### openUrl(...)

```
openUrl(options: OpenUrlOptions) => Promise<OpenUrlResult>
```

Open an app with the given URL.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `OpenUrlOptions` |

**Returns:** `Promise<OpenUrlResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CanOpenUrlResult

| Prop        | Type      | Description                                                                                                                                                  | Since |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`value`** | `boolean` | Whether or not the app can be opened with the given URL. On the web, this is always `true` because the browser cannot determine whether a URL can be opened. | 0.1.0 |

#### CanOpenUrlOptions

| Prop      | Type     | Description                                                                                                                                                                           | Since |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`url`** | `string` | The URL to check. On **iOS**, this must be a URL scheme (e.g. `mailto:`). On **Android**, this can be a URL scheme (e.g. `mailto:`) or a package name (e.g. `com.google.android.gm`). | 0.1.0 |

#### OpenUrlResult

| Prop            | Type      | Description                                     | Since |
| --------------- | --------- | ----------------------------------------------- | ----- |
| **`completed`** | `boolean` | Whether or not the app was opened successfully. | 0.1.0 |

#### OpenUrlOptions

| Prop      | Type     | Description                                                                                                                                                                          | Since |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`url`** | `string` | The URL to open. On **iOS**, this must be a URL scheme (e.g. `mailto:`). On **Android**, this can be a URL scheme (e.g. `mailto:`) or a package name (e.g. `com.google.android.gm`). | 0.1.0 |

## Migrating from `@capacitor/app-launcher`

This plugin is a drop-in replacement for the official `@capacitor/app-launcher` plugin. The API is identical, so you only need to change the import and installation.

| `@capacitor/app-launcher`         | App Launcher                      |
| --------------------------------- | --------------------------------- |
| `AppLauncher.canOpenUrl({ url })` | `AppLauncher.canOpenUrl({ url })` |
| `AppLauncher.openUrl({ url })`    | `AppLauncher.openUrl({ url })`    |

On Android, the `url` may be a URL scheme or a package name for both `canOpenUrl(...)` and `openUrl(...)`.

## FAQ

### How is this plugin different from other similar plugins?

It lets you both check whether an app can be opened and open it, and on Android the target can be a URL scheme or a package name, so you can launch a specific app like Gmail directly by its package. It uses only official platform APIs, keeping it safe for App Store and Google Play submissions, and pairs cleanly with the Maps Launcher and Settings Launcher plugins for a complete launching story. The API is fully typed, supports both CocoaPods and Swift Package Manager on iOS, and is actively maintained against the latest Capacitor and OS versions.

### Why does `canOpenUrl` always return `false`?

This usually means the URL scheme or package name is not declared in your app. On Android 11 (API level 30) and above, every package name and URL scheme must be declared in the `<queries>` element of your `AndroidManifest.xml`. On iOS, every URL scheme must be declared in the `LSApplicationQueriesSchemes` key of your `Info.plist`. See the [Installation](#installation) section for examples.

### Can I open an app by its package name?

Yes, but only on Android, where the `url` option accepts a URL scheme (e.g. `mailto:`) or a package name (e.g. `com.google.android.gm`). On iOS, only URL schemes are supported.

### How can I check if an app is installed?

Use `canOpenUrl(...)` with the app's URL scheme or, on Android, its package name. Make sure the scheme or package name is declared as described in the [Installation](#installation) section. Note that on the Web, this method always resolves with `value: true` because the browser cannot determine whether a URL can be opened.

### How is this plugin different from the official `@capacitor/app-launcher` plugin?

This plugin is a drop-in replacement with an identical API, so you only need to change the import and installation. In addition, on Android the `url` may also be a package name for both `canOpenUrl(...)` and `openUrl(...)`. See the [migration section](#migrating-from-capacitorapp-launcher) for details.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/): Launch arbitrary Android intents.
- [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/): Launch navigation apps with turn-by-turn directions.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-launcher/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-launcher/LICENSE).

# Capacitor App Review Plugin

Capacitor plugin that allows users to submit app store reviews and ratings.

## Use Cases

The App Review plugin is typically used to collect more app store ratings and reviews, for example:

- **In-app review prompts**: Ask for a rating at a positive moment, such as after a completed task, without the user leaving the app.
- **Rate this app button**: Open the app store page directly from a button in your settings or about screen.
- **Feedback flows**: Route satisfied users from your own feedback dialog to the native review dialog or the app store review page.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-review` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-review
npx cap sync
```

### Android

#### 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:

- `$androidPlayReviewVersion` version of `com.google.android.play:review` (default: `2.0.2`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to request an in-app review and open the app store page.

### Request an in-app review

Show the native in-app review dialog so the user can rate your app without leaving it. Note that on iOS, review requests are limited to 3 requests per year. Only available on Android, and on iOS 14 and later:

```
import { AppReview } from '@capawesome/capacitor-app-review';

const requestReview = async () => {
  await AppReview.requestReview();
};
```

### Open the app store page

Open the App Store page for the current app and, if possible, open the dialog to leave a review. On iOS, you can pass the Apple ID of your app via the `appId` option. Only available on Android and iOS:

```
import { AppReview } from '@capawesome/capacitor-app-review';

const openAppStore = async () => {
  await AppReview.openAppStore();
};
```

## API

- [`openAppStore(...)`](#openappstore)
- [`requestReview()`](#requestreview)
- [Interfaces](#interfaces)

### openAppStore(...)

```
openAppStore(options?: OpenAppStoreOptions | undefined) => Promise<void>
```

Open the App Store page for the current app and, if possible, open the dialog to leave a review.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `OpenAppStoreOptions` |

**Since:** 6.0.0

______________________________________________________________________

### requestReview()

```
requestReview() => Promise<void>
```

Request an in-app review.

**Attention**: On iOS, review requests are limited to 3 requests per year.

Only available on Android and iOS (14+).

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### OpenAppStoreOptions

| Prop        | Type     | Description                                                                                                                                                                                                                                     | Since |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`appId`** | `string` | The app ID of the app to open in the App Store. On **iOS**, this is the Apple ID of your app (e.g. `123456789`). You can find the ID in the URL of your app store entry (e.g. `https://apps.apple.com/app/id123456789`). Only available on iOS. | 6.0.1 |

## Testing

In order to test the In-App Review functionality, you need to follow the instructions provided by the respective platform:

- [Android](https://developer.android.com/guide/playcore/in-app-review/test)
- [iOS](https://developer.apple.com/documentation/storekit/skstorereviewcontroller/3566727-requestreview#4278434)

## FAQ

### Why is the in-app review dialog not showing up?

The operating system decides whether the review dialog is actually displayed. On iOS, review requests are limited to 3 requests per year, so the dialog may not appear every time you call `requestReview()`. Both platforms also have special requirements for testing, see the [Testing](#testing) section for the official instructions.

### What is the difference between `requestReview` and `openAppStore`?

The `requestReview()` method shows the native in-app review dialog, so the user can rate your app without leaving it. The `openAppStore(...)` method opens the App Store page for the current app and, if possible, opens the dialog to leave a review there. Use `requestReview()` for gentle prompts and `openAppStore(...)` for an explicit "Rate this app" button.

### Do I need to provide an `appId`?

Only on iOS, where the `appId` option of `openAppStore(...)` is the Apple ID of your app (e.g. `123456789`). You can find the ID in the URL of your app store entry (e.g. `https://apps.apple.com/app/id123456789`).

### How can I test the in-app review functionality?

You need to follow the instructions provided by the respective platform, since in-app reviews behave differently in development and production environments. The official testing guides for Android and iOS are linked in the [Testing](#testing) section.

### Which platforms are supported?

The plugin supports Android and iOS. The `requestReview()` method requires iOS 14 or later, and the `openAppStore(...)` method is available on Android and iOS.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist your users with native app updates.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon.
- [Install Referrer](https://capawesome.io/docs/sdks/capacitor/install-referrer/): Read install attribution data from the Play Install Referrer and Apple Ad Services.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-review/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-review/LICENSE).

# Capacitor App Shortcuts Plugin

Capacitor plugin to manage app shortcuts and quick actions.

## Use Cases

The App Shortcuts plugin is typically used to give users faster access to key parts of your app right from the home screen icon, for example:

- **Quick actions**: Let users jump directly to frequently used screens such as search, compose, or feedback.
- **Dynamic shortcuts**: Create or update shortcuts at runtime based on user behavior, for example a shortcut to the most recently opened item.
- **Default shortcuts**: Define a set of default shortcuts in your Capacitor configuration without writing any code.
- **Deep linking**: React to shortcut clicks with the `click` listener and navigate the user to the corresponding screen.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/app-shortcuts/example).

| Android | iOS |
| ------- | --- |
|         |     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-shortcuts` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-app-shortcuts
npx cap sync
```

## Configuration

| Prop            | Type         | Description                                                                                 | Since |
| --------------- | ------------ | ------------------------------------------------------------------------------------------- | ----- |
| **`shortcuts`** | `Shortcut[]` | The list of app shortcuts that should be set by default. Only available on Android and iOS. | 7.2.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "AppShortcuts": {
      "shortcuts": [{ id: 'feedback', title: 'Feedback' }]
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-app-shortcuts" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    AppShortcuts: {
      shortcuts: [{ id: 'feedback', title: 'Feedback' }],
    },
  },
};

export default config;
```

### iOS

On iOS, you must add the following to your app's `AppDelegate.swift`:

```
+ import CapawesomeCapacitorAppShortcuts

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        if let shortcutItem = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
+            NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+            return true
+        }
        return true
    }

+    func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
+        NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+        completionHandler(true)
+    }
```

## Usage

The following examples show how to create, get, and remove app shortcuts and listen for shortcut clicks.

### Create or update app shortcuts

Use the `set(...)` method to create or update the app shortcuts. Each shortcut needs a unique identifier and a title. Only available on Android and iOS:

```
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const set = async () => {
  await AppShortcuts.set({
    shortcuts: [
      {
        id: 'feedback',
        title: 'Feedback',
        description: 'Send us your feedback',
      },
      {
        id: 'rate',
        title: 'Rate',
        description: 'Rate our app',
      }
    ],
  });
};
```

### Get all app shortcuts

Retrieve the list of app shortcuts that are currently set. Only available on Android and iOS:

```
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const get = async () => {
  const result = await AppShortcuts.get();
  return result.shortcuts;
};
```

### Remove all app shortcuts

Clear all app shortcuts, for example when the user signs out. Only available on Android and iOS:

```
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const clear = async () => {
  await AppShortcuts.clear();
};
```

### Listen for shortcut clicks

Add a listener for the `click` event to react when the user taps an app shortcut, for example to navigate to the corresponding screen. On iOS, this requires the changes to your `AppDelegate.swift` described in the [iOS configuration](#ios) instructions:

```
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const addListener = async () => {
  AppShortcuts.addListener('click', (event) => {
    console.log('Shortcut clicked:', event.shortcutId);
  });
};
```

## API

- [`clear()`](#clear)
- [`get()`](#get)
- [`set(...)`](#set)
- [`addListener('click', ...)`](#addlistenerclick-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### clear()

```
clear() => Promise<void>
```

Remove all app shortcuts.

Only available on Android and iOS.

**Since:** 6.0.0

______________________________________________________________________

### get()

```
get() => Promise<GetResult>
```

Get all app shortcuts.

Only available on Android and iOS.

**Returns:** `Promise<GetResult>`

**Since:** 6.0.0

______________________________________________________________________

### set(...)

```
set(options: SetOptions) => Promise<void>
```

Create or update app shortcuts.

Only available on Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `SetOptions` |

**Since:** 6.0.0

______________________________________________________________________

### addListener('click', ...)

```
addListener(eventName: 'click', listenerFunc: (event: ClickEvent) => void) => Promise<PluginListenerHandle>
```

Called when an app shortcut is clicked.

Only available on Android and iOS.

| Param              | Type                          |
| ------------------ | ----------------------------- |
| **`eventName`**    | `'click'`                     |
| **`listenerFunc`** | `(event: ClickEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### GetResult

| Prop            | Type         | Description                | Since |
| --------------- | ------------ | -------------------------- | ----- |
| **`shortcuts`** | `Shortcut[]` | The list of app shortcuts. | 6.0.0 |

#### Shortcut

| Prop              | Type     | Description                                                                                                                                                                                  | Since                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`description`** | `string` | The description. On **Android**, the launcher shows this instead of the short title when it has enough space. **Attention**: On **iOS**, the icon and the description must be used together. | 6.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **`id`**          | `string` | The unique identifier.                                                                                                                                                                       | 6.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **`title`**       | `string` | The display name.                                                                                                                                                                            | 6.0.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **`icon`**        | \`string | number\`                                                                                                                                                                                     | The icon to display. On **Android**, the icon can be one of the following: - An integer value of the [R.drawable](https://developer.android.com/reference/android/R.drawable) enum (e.g. `17301547`). - A string that represents the name of the drawable resource (e.g. `"alert_dark_frame"`). - A base64 encoded image string (e.g. `"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."`). On **iOS**, the icon can be one of the following: - The constant integer value of the [UIApplicationShortcutIcon.IconType](https://developer.apple.com/documentation/uikit/uiapplicationshortcuticon/icontype) enum (e.g. `6`). - A system symbol name (e.g. `star.fill`). - Name of the image asset from the asset catalogue. |
| **`androidIcon`** | \`string | number\`                                                                                                                                                                                     | The icon to display on Android. The icon can be one of the following: - An integer value of the [R.drawable](https://developer.android.com/reference/android/R.drawable) enum (e.g. `17301547`). - A string that represents the name of the drawable resource (e.g. `"alert_dark_frame"`). - A base64 encoded image string (e.g. `"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."`).                                                                                                                                                                                                                                                                                                                                     |
| **`iosIcon`**     | \`string | number\`                                                                                                                                                                                     | The icon to display on iOS. The icon can be one of the following: - The constant integer value of the [UIApplicationShortcutIcon.IconType](https://developer.apple.com/documentation/uikit/uiapplicationshortcuticon/icontype) enum (e.g. `6`). - A system symbol name (e.g. `star.fill`). - Name of the image asset from the asset catalogue.                                                                                                                                                                                                                                                                                                                                                                                       |

#### SetOptions

| Prop            | Type         | Description                | Since |
| --------------- | ------------ | -------------------------- | ----- |
| **`shortcuts`** | `Shortcut[]` | The list of app shortcuts. | 6.0.0 |

#### PluginListenerHandle

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

#### ClickEvent

| Prop             | Type     | Description                                                 | Since |
| ---------------- | -------- | ----------------------------------------------------------- | ----- |
| **`shortcutId`** | `string` | The unique identifier of the app shortcut that was clicked. | 6.0.0 |

## FAQ

### Which platforms are supported by this plugin?

App shortcuts are a native concept of the Android launcher and the iOS home screen, so the plugin is only available on Android and iOS. All plugin methods and the `click` event are marked as only available on Android and iOS in the [API](#api) section.

### Why is the click listener not called on iOS?

On iOS, the plugin relies on changes to your app's `AppDelegate.swift` to forward shortcut items to the plugin. Make sure you have applied the code changes described in the [iOS configuration](#ios) instructions. Without them, the `click` event is never delivered.

### Can I define app shortcuts without writing any code?

Yes, you can use the `shortcuts` configuration option to define a list of app shortcuts that are set by default. See the [Configuration](#configuration) section for examples in `capacitor.config.json` and `capacitor.config.ts`.

### Can I use different icons on Android and iOS?

Yes, you can use the `androidIcon` and `iosIcon` properties to provide platform-specific icons, or the `icon` property for both platforms. On Android, drawable resources and base64 encoded images are supported, while on iOS you can use system symbol names, asset catalogue images, or `UIApplicationShortcutIcon` types. Note that on iOS, the icon and the description must be used together.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Icon](https://capawesome.io/docs/sdks/capacitor/app-icon/): Change the app icon at runtime.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-shortcuts/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-shortcuts/LICENSE).

# Capacitor App Tracking Transparency Plugin

Capacitor plugin for the [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency) framework.

## Features

The Capacitor App Tracking Transparency plugin is one of the most complete tracking authorization solutions for Capacitor apps. Here are some of the key features:

- 🔒 **Authorization status**: Read the current tracking authorization status.
- 🙋 **Permission request**: Present the system tracking authorization prompt.
- 🆔 **Advertising identifier**: Read the advertising identifier (IDFA) when authorized.
- 🤝 **Compatibility**: Works alongside the [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Tracking Transparency plugin is typically used whenever an iOS app collects data for tracking purposes, for example:

- **Personalized ads**: Request tracking permission before serving personalized ads to the user.
- **Ad attribution**: Read the advertising identifier (IDFA) to attribute app installs to ad campaigns once the user has authorized tracking.
- **Conditional tracking**: Check the current tracking authorization status and only enable tracking-related features when the status is `authorized`.
- **App Review compliance**: Present the system tracking authorization prompt as required by Apple for any app that tracks users.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-tracking-transparency` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-tracking-transparency
npx cap sync
```

This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented.

### iOS

#### Privacy Descriptions

The `NSUserTrackingUsageDescription` key must be added to the `Info.plist` file of your app. Otherwise, the `requestPermission(...)` method will reject with an error.

```
<key>NSUserTrackingUsageDescription</key>
<string>Your data will be used to deliver personalized ads to you.</string>
```

The purpose string must clearly explain why your app is requesting permission to track the user. See the [Apple documentation](https://developer.apple.com/documentation/bundleresources/information-property-list/nsusertrackingusagedescription) for more information.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check the tracking authorization status, request tracking permission, and read the advertising identifier.

### Check the tracking authorization status

Read the current tracking authorization status, for example to decide whether tracking-related features should be enabled. Only available on iOS:

```
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getStatus = async () => {
  const { status } = await AppTrackingTransparency.getStatus();
  return status;
};
```

### Request tracking permission

Present the system tracking authorization prompt. The prompt is only shown once per install while the status is `notDetermined`; afterwards, the method resolves with the existing status. Only available on iOS:

```
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const requestPermission = async () => {
  const { status } = await AppTrackingTransparency.requestPermission();
  return status;
};
```

### Read the advertising identifier

Read the advertising identifier (IDFA) of the device. It is only available if the tracking authorization status is `authorized`; otherwise, `null` is returned. Only available on iOS:

```
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getAdvertisingIdentifier = async () => {
  const { advertisingIdentifier } =
    await AppTrackingTransparency.getAdvertisingIdentifier();
  return advertisingIdentifier;
};
```

## API

- [`getAdvertisingIdentifier()`](#getadvertisingidentifier)
- [`getStatus()`](#getstatus)
- [`requestPermission()`](#requestpermission)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getAdvertisingIdentifier()

```
getAdvertisingIdentifier() => Promise<GetAdvertisingIdentifierResult>
```

Get the advertising identifier (IDFA) of the device.

The advertising identifier is only available if the tracking authorization status is `authorized`. Otherwise, `null` is returned.

**Note**: The iOS Simulator always returns `null`, even if the tracking authorization status is `authorized`. Use a real device to test this method.

Only available on iOS.

**Returns:** `Promise<GetAdvertisingIdentifierResult>`

**Since:** 0.1.0

______________________________________________________________________

### getStatus()

```
getStatus() => Promise<GetStatusResult>
```

Get the current tracking authorization status.

Only available on iOS.

**Returns:** `Promise<GetStatusResult>`

**Since:** 0.1.0

______________________________________________________________________

### requestPermission()

```
requestPermission() => Promise<RequestPermissionResult>
```

Request permission to track the user.

This will present the system tracking authorization prompt if the status has not been determined yet. The prompt is only shown once per install.

The `NSUserTrackingUsageDescription` key must be added to the `Info.plist` file of your app.

Only available on iOS.

**Returns:** `Promise<RequestPermissionResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetAdvertisingIdentifierResult

| Prop                        | Type     | Description | Since                                                                                                                                                                                                                 |
| --------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`advertisingIdentifier`** | \`string | null\`      | The advertising identifier (IDFA) of the device. Returns `null` if the tracking authorization status is not `authorized` or if no advertising identifier is available, which is always the case on the iOS Simulator. |

#### GetStatusResult

| Prop         | Type             | Description                                | Since |
| ------------ | ---------------- | ------------------------------------------ | ----- |
| **`status`** | `TrackingStatus` | The current tracking authorization status. | 0.1.0 |

#### RequestPermissionResult

| Prop         | Type             | Description                                          | Since |
| ------------ | ---------------- | ---------------------------------------------------- | ----- |
| **`status`** | `TrackingStatus` | The tracking authorization status after the request. | 0.1.0 |

### Type Aliases

#### TrackingStatus

The tracking authorization status.

- `authorized`: The user authorized access to app-related data for tracking.
- `denied`: The user denied access to app-related data for tracking.
- `notDetermined`: The user has not yet received a tracking authorization request.
- `restricted`: Tracking authorization is restricted and cannot be changed by the user.

`'authorized' | 'denied' | 'notDetermined' | 'restricted'`

## App Review Guidance

Apple requires that any app that tracks users requests permission via the App Tracking Transparency framework. Keep the following guidelines in mind to avoid App Review rejections:

- **Prompt timing**: Call `requestPermission(...)` only when the user is in a context where tracking makes sense. The system prompt is only shown once per install while the status is `notDetermined`. Calling the method again afterwards resolves with the existing status without showing the prompt.
- **Purpose string**: The `NSUserTrackingUsageDescription` purpose string must accurately describe how the collected data is used. Vague or misleading descriptions are a common reason for rejection.
- **Advertising identifier**: The advertising identifier (IDFA) is only available while the status is `authorized`. In all other cases, `getAdvertisingIdentifier(...)` returns `null`.
- **Simulator**: The iOS Simulator never provides an advertising identifier, so `getAdvertisingIdentifier(...)` always returns `null` there, even if the status is `authorized`. Use a real device to test the advertising identifier.

## FAQ

### How is this plugin different from other similar plugins?

It wraps Apple's App Tracking Transparency framework in a small, fully typed API: read the current authorization status, present the system prompt, and read the advertising identifier (IDFA) once the user has authorized tracking. It also ships focused App Review guidance on prompt timing, purpose strings, and simulator behavior — the details that most often decide whether a tracking-enabled app is approved. It supports CocoaPods and Swift Package Manager and is actively maintained against the latest Capacitor version.

### Does this plugin work on Android or Web?

No, the App Tracking Transparency framework is an iOS-only concept. The plugin is only available on iOS; on Android and Web, all methods reject as unimplemented.

### Why does the requestPermission method reject with an error?

The most common reason is a missing `NSUserTrackingUsageDescription` key in your app's `Info.plist` file. This key is required for the system tracking authorization prompt and its purpose string must clearly explain why your app is requesting permission to track the user. See the [Installation](#installation) section for details.

### Why is the tracking authorization prompt not shown?

The system prompt is only shown once per install while the tracking authorization status is `notDetermined`. If the user has already responded to the prompt, calling `requestPermission()` again resolves with the existing status without showing the prompt. To test the prompt again, reinstall the app.

### Why does getAdvertisingIdentifier return null?

The advertising identifier (IDFA) is only available if the tracking authorization status is `authorized`; in all other cases, `null` is returned. Additionally, the iOS Simulator never provides an advertising identifier, even if the status is `authorized`, so use a real device to test this method.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/): Check and request device permissions with a unified API.
- [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/): Hide sensitive app content in the app switcher and block screenshots.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-tracking-transparency/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-tracking-transparency/LICENSE).

# Capacitor App Update Plugin

Capacitor plugin that assists with native app updates. It supports retrieving app update information on **Android** and **iOS** and supports [in-app updates](https://developer.android.com/guide/playcore/in-app-updates) on **Android**.

> Check out the [Capacitor Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/) plugin to update your app remotely in real-time without submitting a new version to the app store. 🚀

## Features

The Capacitor App Update plugin is one of the most complete native app update solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📱 **App update information**: Retrieves current and available app versions.
- ⚡ **Immediate in-app updates**: Performs immediate updates on Android.
- 📲 **Flexible in-app updates**: Supports flexible update flows on Android.
- 📈 **Update priority**: Supports update priority levels on Android.
- 🏪 **App store navigation**: Opens the app store entry for manual updates.
- 📊 **Update state tracking**: Monitors flexible update progress with listeners.
- 🤝 **Compatibility**: Works alongside the [Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/) plugin.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The App Update plugin is typically used to make sure users are running a recent version of your app, for example:

- **Force updates**: Perform an immediate in-app update on Android when a critical new version must be installed before the app can be used.
- **Optional update prompts**: Start a flexible in-app update on Android that downloads in the background and track its progress with the state change listener.
- **Version checks**: Compare the current app version with the version available in the Play Store or App Store to decide whether to inform the user.
- **Store redirects**: Open the app's Play Store or App Store entry so the user can update the app manually, for example on iOS where in-app updates are not available.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-update` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-app-update
npx cap sync
```

### Android 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:

- `$androidPlayAppUpdateVersion` version of `com.google.android.play:app-update` (default: `2.1.0`)
- `$androidPlayServicesBaseVersion` version of `com.google.android.gms:play-services-base` (default: `18.9.0`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get app update information, open the app store entry, and perform immediate and flexible in-app updates.

### Get app update information

Use `getAppUpdateInfo()` to retrieve the current and available app versions. On Android, versions are identified by the version code; on iOS, by the version name. Only available on Android and iOS:

```
import { AppUpdate } from '@capawesome/capacitor-app-update';
import { Capacitor } from '@capacitor/core';

const getCurrentAppVersion = async () => {
  const result = await AppUpdate.getAppUpdateInfo();
  if (Capacitor.getPlatform() === 'android') {
    return result.currentVersionCode;
  } else {
    return result.currentVersionName;
  }
};

const getAvailableAppVersion = async () => {
  const result = await AppUpdate.getAppUpdateInfo();
  if (Capacitor.getPlatform() === 'android') {
    return result.availableVersionCode;
  } else {
    return result.availableVersionName;
  }
};
```

### Open the app store entry

Open the app's page in the Play Store (Android) or App Store (iOS) so the user can update the app manually. Only available on Android and iOS:

```
import { AppUpdate } from '@capawesome/capacitor-app-update';

const openAppStore = async () => {
  await AppUpdate.openAppStore();
};
```

### Perform an immediate update

Perform an immediate in-app update if an update is available and an immediate update is allowed. Only available on Android:

```
import { AppUpdate, AppUpdateAvailability } from '@capawesome/capacitor-app-update';

const performImmediateUpdate = async () => {
  const result = await AppUpdate.getAppUpdateInfo();
  if (result.updateAvailability !== AppUpdateAvailability.UPDATE_AVAILABLE) {
    return;
  }
  if (result.immediateUpdateAllowed) {
    await AppUpdate.performImmediateUpdate();
  }
};
```

### Start a flexible update

Start a flexible in-app update if an update is available and a flexible update is allowed. You can monitor the download progress with the `onFlexibleUpdateStateChange` listener. Only available on Android:

```
import { AppUpdate, AppUpdateAvailability } from '@capawesome/capacitor-app-update';

const startFlexibleUpdate = async () => {
  const result = await AppUpdate.getAppUpdateInfo();
  if (result.updateAvailability !== AppUpdateAvailability.UPDATE_AVAILABLE) {
    return;
  }
  if (result.flexibleUpdateAllowed) {
    await AppUpdate.startFlexibleUpdate();
  }
};
```

### Complete a flexible update

Complete a flexible in-app update by restarting the app. Only available on Android:

```
import { AppUpdate } from '@capawesome/capacitor-app-update';

const completeFlexibleUpdate = async () => {
  await AppUpdate.completeFlexibleUpdate();
};
```

## API

- [`getAppUpdateInfo(...)`](#getappupdateinfo)
- [`openAppStore(...)`](#openappstore)
- [`performImmediateUpdate()`](#performimmediateupdate)
- [`startFlexibleUpdate()`](#startflexibleupdate)
- [`completeFlexibleUpdate()`](#completeflexibleupdate)
- [`addListener('onFlexibleUpdateStateChange', ...)`](#addlisteneronflexibleupdatestatechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getAppUpdateInfo(...)

```
getAppUpdateInfo(options?: GetAppUpdateInfoOptions | undefined) => Promise<AppUpdateInfo>
```

Returns app update informations.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `GetAppUpdateInfoOptions` |

**Returns:** `Promise<AppUpdateInfo>`

______________________________________________________________________

### openAppStore(...)

```
openAppStore(options?: OpenAppStoreOptions | undefined) => Promise<void>
```

Opens the app store entry of the app in the Play Store (Android) or App Store (iOS).

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `OpenAppStoreOptions` |

______________________________________________________________________

### performImmediateUpdate()

```
performImmediateUpdate() => Promise<AppUpdateResult>
```

Performs an immediate in-app update.

Only available on Android.

**Returns:** `Promise<AppUpdateResult>`

______________________________________________________________________

### startFlexibleUpdate()

```
startFlexibleUpdate() => Promise<AppUpdateResult>
```

Starts a flexible in-app update.

Only available on Android.

**Returns:** `Promise<AppUpdateResult>`

______________________________________________________________________

### completeFlexibleUpdate()

```
completeFlexibleUpdate() => Promise<void>
```

Completes a flexible in-app update by restarting the app.

Only available on Android.

______________________________________________________________________

### addListener('onFlexibleUpdateStateChange', ...)

```
addListener(eventName: 'onFlexibleUpdateStateChange', listenerFunc: (state: FlexibleUpdateState) => void) => Promise<PluginListenerHandle>
```

Adds a flexbile in-app update state change listener.

Only available on Android.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'onFlexibleUpdateStateChange'`        |
| **`listenerFunc`** | `(state: FlexibleUpdateState) => void` |

**Returns:** `Promise<PluginListenerHandle>`

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

______________________________________________________________________

### Interfaces

#### AppUpdateInfo

| Prop                              | Type                          | Description                                                                                                                                                                                                                                  | Since |
| --------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`currentVersionName`**          | `string`                      | The current version name of the app. On **Android**, this is the `versionName` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file. Only available on Android and iOS. | 5.1.0 |
| **`availableVersionName`**        | `string`                      | The available version name of the update. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file. Only available on iOS.                                                                                            | 5.1.0 |
| **`currentVersionCode`**          | `string`                      | The current version code of the app. On **Android**, this is the `versionCode` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file. Only available on Android and iOS.            | 5.1.0 |
| **`availableVersionCode`**        | `string`                      | The available version code of the update. On **Android**, this is the `versionCode` from the `android/app/build.gradle` file. Only available on Android.                                                                                     | 5.1.0 |
| **`availableVersionReleaseDate`** | `string`                      | Release date of the update in ISO 8601 (UTC) format. Only available on iOS.                                                                                                                                                                  |       |
| **`updateAvailability`**          | `AppUpdateAvailability`       | The app update availability. Only available on Android and iOS.                                                                                                                                                                              |       |
| **`updatePriority`**              | `number`                      | In-app update priority for this update, as defined by the developer in the Google Play Developer API. Only available on Android.                                                                                                             |       |
| **`immediateUpdateAllowed`**      | `boolean`                     | `true` if an immediate update is allowed, otherwise `false`. Only available on Android.                                                                                                                                                      |       |
| **`flexibleUpdateAllowed`**       | `boolean`                     | `true` if a flexible update is allowed, otherwise `false`. Only available on Android.                                                                                                                                                        |       |
| **`clientVersionStalenessDays`**  | `number`                      | Number of days since the Google Play Store app on the user's device has learnt about an available update if an update is available or in progress. Only available on Android.                                                                |       |
| **`installStatus`**               | `FlexibleUpdateInstallStatus` | Flexible in-app update install status. Only available on Android.                                                                                                                                                                            |       |
| **`minimumOsVersion`**            | `string`                      | The minimum version of the operating system required for the app to run in iOS. Only available on iOS.                                                                                                                                       |       |

#### GetAppUpdateInfoOptions

| Prop          | Type     | Description                                                                                                                                                               |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`country`** | `string` | The two-letter country code for the store you want to search. See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a list of ISO Country Codes. Only available on iOS. |

#### OpenAppStoreOptions

| Prop                     | Type     | Description                                                                                                                                                                                                                                                                                    | Since |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`androidPackageName`** | `string` | The package name of the app to open in the Play Store. On **Android**, this is the application ID of your app (e.g. `com.example.app`). You can find the ID in the `android/app/build.gradle` file. If not provided, the current app's package name will be used. Only available on Android.   | 7.2.0 |
| **`appId`**              | `string` | The app ID of the app to open in the App Store. On **iOS**, this is the Apple ID of your app (e.g. `123456789`). You can find the ID in the URL of your app store entry (e.g. `https://apps.apple.com/app/id123456789`). **Attention**: This option is required on iOS. Only available on iOS. | 6.1.0 |

#### AppUpdateResult

| Prop       | Type                  |
| ---------- | --------------------- |
| **`code`** | `AppUpdateResultCode` |

#### PluginListenerHandle

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

#### FlexibleUpdateState

| Prop                       | Type                          | Description                                                                                                                        |
| -------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **`installStatus`**        | `FlexibleUpdateInstallStatus` | Flexible in-app update install status.                                                                                             |
| **`bytesDownloaded`**      | `number`                      | Returns the number of bytes downloaded so far. `undefined` if the install status is other than `DOWNLOADING`.                      |
| **`totalBytesToDownload`** | `number`                      | Returns the total number of bytes to be downloaded for this update. `undefined` if the install status is other than `DOWNLOADING`. |

### Enums

#### AppUpdateAvailability

| Members                    | Value |
| -------------------------- | ----- |
| **`UNKNOWN`**              | `0`   |
| **`UPDATE_NOT_AVAILABLE`** | `1`   |
| **`UPDATE_AVAILABLE`**     | `2`   |
| **`UPDATE_IN_PROGRESS`**   | `3`   |

#### FlexibleUpdateInstallStatus

| Members           | Value |
| ----------------- | ----- |
| **`UNKNOWN`**     | `0`   |
| **`PENDING`**     | `1`   |
| **`DOWNLOADING`** | `2`   |
| **`INSTALLING`**  | `3`   |
| **`INSTALLED`**   | `4`   |
| **`FAILED`**      | `5`   |
| **`CANCELED`**    | `6`   |
| **`DOWNLOADED`**  | `11`  |

#### AppUpdateResultCode

| Members             | Value | Description                                                                                 |
| ------------------- | ----- | ------------------------------------------------------------------------------------------- |
| **`OK`**            | `0`   | The user has accepted the update.                                                           |
| **`CANCELED`**      | `1`   | The user has denied or cancelled the update.                                                |
| **`FAILED`**        | `2`   | Some other error prevented either the user from providing consent or the update to proceed. |
| **`NOT_AVAILABLE`** | `3`   | No update available.                                                                        |
| **`NOT_ALLOWED`**   | `4`   | Update type not allowed.                                                                    |
| **`INFO_MISSING`**  | `5`   | App update info missing. You must call `getAppUpdateInfo()` before requesting an update.    |

## Test with internal app-sharing

The Android Developers documentation describes how to test [in-app updates](https://developer.android.com/guide/playcore/in-app-updates) using [internal app sharing](https://developer.android.com/guide/playcore/in-app-updates/test).

## FAQ

### What is the difference between this plugin and the Live Update plugin?

The App Update plugin assists with native app updates that are distributed through the Play Store or App Store, for example by retrieving update information or performing in-app updates on Android. The [Capacitor Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/) plugin, on the other hand, updates your app remotely in real-time without submitting a new version to the app store.

### Are in-app updates available on iOS?

No, in-app updates are a feature of the Google Play Store and are therefore only available on Android. On iOS, you can use `getAppUpdateInfo(...)` to check whether an update is available and then call `openAppStore(...)` to open the app's App Store entry so the user can update manually.

### What is the difference between an immediate and a flexible update?

An immediate update is performed in one step with `performImmediateUpdate()`. A flexible update is started with `startFlexibleUpdate()`, its download progress can be monitored with the `onFlexibleUpdateStateChange` listener, and it is completed by calling `completeFlexibleUpdate()`, which restarts the app. Both update types are only available on Android.

### Why does the update fail with the INFO_MISSING result code?

The `INFO_MISSING` result code means that the app update information is missing. You must call `getAppUpdateInfo(...)` before requesting an update with `performImmediateUpdate()` or `startFlexibleUpdate()`.

### How can I test in-app updates on Android?

The Android Developers documentation describes how to test in-app updates using internal app sharing. See the [Test with internal app-sharing](#test-with-internal-app-sharing) section for the relevant links.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/): Let users submit app store reviews and ratings.
- [Google Play Services](https://capawesome.io/docs/sdks/capacitor/google-play-services/): Check whether Google Play Services is available on the device and prompt the user to install or update it.
- [Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/): Update your app remotely in real-time without requiring users to download a new version from the app store.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-update/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-update/LICENSE).

## Credits

This plugin is based on the [Capacitor App Update](https://github.com/capawesome-team/capacitor-app-update) plugin. Thanks to everyone who contributed to the project!

# Capacitor Apple Sign-In Plugin

Unofficial Capacitor plugin to sign-in with Apple.[1](#fn:1)

## Features

The Capacitor Apple Sign-In plugin is one of the most complete Apple authentication solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🍎 **Native Sign-In**: Uses native AuthenticationServices on iOS.
- 🌐 **WebView OAuth**: Implements Apple OAuth flow on Android without external dependencies.
- 📧 **Scope support**: Request email and full name on all platforms.
- 🔐 **Nonce & state**: Supports nonce for replay protection and state for CSRF protection.
- 🪶 **Lightweight**: Just a single dependency and zero unnecessary bloat.
- 🤝 **Compatibility**: Compatible with the [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/) and [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Apple Sign-In plugin is typically used to let users authenticate with their Apple ID, for example:

- **User authentication**: Offer Sign in with Apple as a login option in your app on Android, iOS, and Web.
- **Account creation**: Request the user's email address and full name during sign-up using the email and full name scopes.
- **Backend integration**: Send the authorization code and ID token to your backend to verify the sign-in and create a user session.
- **Secure sign-in flows**: Pass a nonce for replay protection and a state value for CSRF protection.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Guides

- [How to Sign In with Apple using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-apple-using-capacitor/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-apple-sign-in` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-apple-sign-in
npx cap sync
```

### iOS

Add the **Sign in with Apple** capability to your app in Xcode:

1. Open your app target in Xcode.
1. Go to the **Signing & Capabilities** tab.
1. Click **+ Capability** and add **Sign in with Apple**.

### Web

The plugin loads the [Apple JS SDK](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js) automatically. Make sure you have configured your Apple Service ID with the correct redirect URL and web domain in the [Apple Developer Portal](https://developer.apple.com/account/resources/identifiers/list/serviceId).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize the plugin and sign in with Apple.

### Initialize the plugin

On Android and Web, you must initialize the plugin with your Apple Service ID before calling `signIn(...)`. This method is only available on Android and Web:

```
import { AppleSignIn } from '@capawesome/capacitor-apple-sign-in';

const initialize = async () => {
  await AppleSignIn.initialize({
    clientId: 'com.example.app.signin',
  });
};
```

### Sign in with Apple

Start the sign-in flow and receive the authorization code and ID token. Use the `scopes` option to request the user's email address and full name, and pass a `nonce` for replay protection. The `redirectUrl` and `state` options are only available on Android and Web:

```
import { AppleSignIn, SignInScope } from '@capawesome/capacitor-apple-sign-in';

const signIn = async () => {
  const result = await AppleSignIn.signIn({
    scopes: [SignInScope.Email, SignInScope.FullName],
    redirectUrl: 'https://example.com/callback',
    nonce: 'random-nonce',
    state: 'random-state',
  });
  return result;
};
```

## API

- [`initialize(...)`](#initialize)
- [`signIn(...)`](#signin)
- [Interfaces](#interfaces)
- [Enums](#enums)

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the plugin.

This method must be called before `signIn()` on **Android** and **Web**.

Only available on Android and Web.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### signIn(...)

```
signIn(options?: SignInOptions | undefined) => Promise<SignInResult>
```

Sign in with Apple.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `SignInOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### InitializeOptions

| Prop           | Type     | Description                              | Since |
| -------------- | -------- | ---------------------------------------- | ----- |
| **`clientId`** | `string` | The Apple Service ID to use for sign-in. | 0.1.0 |

#### SignInResult

| Prop                    | Type             | Description                                                                                             | Since                                                                             |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **`authorizationCode`** | `string`         | The authorization code.                                                                                 | 0.1.0                                                                             |
| **`idToken`**           | `string`         | The ID token (JWT).                                                                                     | 0.1.0                                                                             |
| **`user`**              | `string`         | The stable Apple user identifier. On **Android** and **Web**, this is decoded from the JWT `sub` claim. | 0.1.0                                                                             |
| **`email`**             | \`string         | null\`                                                                                                  | The user's email address. On **iOS**, this is only provided on the first sign-in. |
| **`givenName`**         | \`string         | null\`                                                                                                  | The user's given name. On **iOS**, this is only provided on the first sign-in.    |
| **`familyName`**        | \`string         | null\`                                                                                                  | The user's family name. On **iOS**, this is only provided on the first sign-in.   |
| **`state`**             | `string`         | The state value from the sign-in request. Only available on Android and Web.                            | 0.1.0                                                                             |
| **`realUserStatus`**    | `RealUserStatus` | The real user status. Only available on iOS.                                                            | 0.1.0                                                                             |

#### SignInOptions

| Prop              | Type            | Description                                                                   | Since |
| ----------------- | --------------- | ----------------------------------------------------------------------------- | ----- |
| **`redirectUrl`** | `string`        | The OAuth redirect URL to use for sign-in. Only available on Android and Web. | 0.1.0 |
| **`scopes`**      | `SignInScope[]` | The scopes to request during sign-in.                                         | 0.1.0 |
| **`nonce`**       | `string`        | A nonce for replay protection.                                                | 0.1.0 |
| **`state`**       | `string`        | A state value for CSRF protection. Only available on Android and Web.         | 0.1.0 |

### Enums

#### RealUserStatus

| Members           | Value           | Description                                                   | Since |
| ----------------- | --------------- | ------------------------------------------------------------- | ----- |
| **`LikelyReal`**  | `'LIKELY_REAL'` | The user appears to be a real person.                         | 0.1.0 |
| **`Unknown`**     | `'UNKNOWN'`     | The system can't determine whether the user is a real person. | 0.1.0 |
| **`Unsupported`** | `'UNSUPPORTED'` | The real user status is not supported on this platform.       | 0.1.0 |

#### SignInScope

| Members        | Value         | Description                       | Since |
| -------------- | ------------- | --------------------------------- | ----- |
| **`Email`**    | `'EMAIL'`     | Request the user's email address. | 0.1.0 |
| **`FullName`** | `'FULL_NAME'` | Request the user's full name.     | 0.1.0 |

## Security

This plugin handles the OAuth flow and returns tokens to your app. To keep your integration secure, be aware of the following:

- **Server-side token verification is required.** The `idToken` (JWT) is **not** verified client-side. Your backend **must** verify the JWT signature using [Apple's public keys](https://appleid.apple.com/auth/keys) before trusting any claims (e.g. `user`, `email`). Never use client-side token data for authorization decisions without server-side verification.
- **Validate the `state` parameter.** The plugin passes the `state` value through to the result but does **not** validate it. Your app must compare the returned `state` against the value it originally sent to protect against CSRF attacks.
- **Android uses a WebView-based OAuth flow.** Unlike iOS (which uses native `AuthenticationServices`), the Android implementation renders Apple's sign-in page in a WebView. Unlike a system browser flow, the WebView is controlled by the app and has access to page content. Ensure your `redirectUrl` uses HTTPS and points to a domain you control.

## FAQ

### What's the difference between this plugin and other Apple Sign-In plugins?

This plugin is purpose-built for Apple Sign-In and focuses on providing a clean and modern API with the latest platform features. Here are some of the key differences:

- **Cross-platform**: Supports Android, iOS, and Web.
- **Lightweight**: No unnecessary dependencies. Just Apple Sign-In, nothing else.
- **No deprecated APIs**: Uses the latest platform APIs (AuthenticationServices on iOS).
- **Scope support**: Request email and full name on all platforms.
- **Error codes**: Provides typed error codes for proper error handling.

### Do I need to call initialize on iOS?

No, the `initialize(...)` method is only available on Android and Web, where it must be called before `signIn(...)` to set the Apple Service ID. On iOS, the plugin uses the native AuthenticationServices framework and no initialization is required.

### Why are the email and name only returned on the first sign-in on iOS?

On iOS, Apple only provides the user's email address, given name, and family name on the first sign-in; on subsequent sign-ins, these values are `null`. Make sure to persist this information, for example on your backend, when you receive it for the first time.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Facebook Sign-In](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/): Sign in with Facebook.
- [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/): Sign in with Google.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/apple-sign-in/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/apple-sign-in/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Apple Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Asset Manager Plugin

Capacitor plugin to access native asset files.

## Features

The Capacitor Asset Manager plugin is one of the most complete native asset access solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📂 **Asset copying**: Copy files or directories from app bundle to data directory.
- 📄 **File listing**: List all files in asset directories.
- 📖 **File reading**: Read asset files with Base64 or UTF-8 encoding.
- 🔄 **Bundle access**: Direct access to native app bundle assets.
- 🗂️ **Directory operations**: Handle both individual files and entire directories.
- 📦 **Multiple encodings**: Support for Base64 and UTF-8 file reading.
- 🤝 **Compatibility**: Works alongside the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/), [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) and [Zip](https://capawesome.io/docs/sdks/capacitor/zip/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Asset Manager plugin is typically used whenever an app ships files inside its native bundle that need to be accessed at runtime, for example:

- **Prepopulated data**: Copy bundled files such as databases or sample data from the app bundle to the app's data directory on first launch.
- **Configuration files**: Read bundled configuration files like `capacitor.config.json` using UTF-8 encoding.
- **Asset discovery**: List the files in an asset directory to process them dynamically.
- **Binary assets**: Read bundled binary files as Base64 encoded strings.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-asset-manager` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-asset-manager
npx cap sync
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to copy an asset to the data directory, list asset files, and read an asset file.

### Copy an asset to the data directory

Copy a file or directory from the app bundle to the app's data directory. You can generate the destination path using the `getUri(...)` method of the Capacitor Filesystem plugin. Only available on Android and iOS:

```
import { AssetManager } from '@capawesome/capacitor-asset-manager';
import { Directory, Filesystem } from '@capacitor/filesystem';

const copy = async () => {
  const { uri } = await Filesystem.getUri({
    directory: Directory.Cache,
    path: 'index.html'
  });
  await AssetManager.copy({
    from: 'public/index.html',
    to: uri
  });
};
```

### List asset files

List the files in an asset directory. If no path is specified, the root path is used. Only available on Android and iOS:

```
import { AssetManager } from '@capawesome/capacitor-asset-manager';

const list = async () => {
  await AssetManager.list({
    path: 'public'
  });
};
```

### Read an asset file

Read a file from the app bundle using Base64 (default) or UTF-8 encoding. Avoid reading large files this way, as it can cause out of memory issues; instead, copy them to the app's data directory using the `copy(...)` method and read them from there using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). Only available on Android and iOS:

```
import { AssetManager, Encoding } from '@capawesome/capacitor-asset-manager';

const read = async () => {
  const { data } = await AssetManager.read({
    encoding: Encoding.Utf8,
    path: 'capacitor.config.json'
  });
  return JSON.parse(data);
};
```

## API

- [`copy(...)`](#copy)
- [`list(...)`](#list)
- [`read(...)`](#read)
- [Interfaces](#interfaces)
- [Enums](#enums)

### copy(...)

```
copy(options: CopyOptions) => Promise<void>
```

Copy a file or directory from the app bundle to the app's data directory.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `CopyOptions` |

**Since:** 7.0.0

______________________________________________________________________

### list(...)

```
list(options?: ListOptions | undefined) => Promise<ListResult>
```

List files in a directory.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ListOptions` |

**Returns:** `Promise<ListResult>`

**Since:** 7.0.0

______________________________________________________________________

### read(...)

```
read(options: ReadOptions) => Promise<ReadResult>
```

Read a file from the app bundle.

**Attention**: Reading large files can cause out of memory (OOM) issues. It is therefore recommended to copy files to the app's data directory using the `copy` method and read them from there using the [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ReadOptions` |

**Returns:** `Promise<ReadResult>`

**Since:** 7.0.0

______________________________________________________________________

### Interfaces

#### CopyOptions

| Prop       | Type     | Description                                                                                                                                                                            | Since |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`from`** | `string` | The source path to copy from.                                                                                                                                                          | 7.0.0 |
| **`to`**   | `string` | The destination path to copy to. **Tip**: Generate this path using the [`getUri(...)`](https://capacitorjs.com/docs/apis/filesystem#geturi) method of the Capacitor Filesystem plugin. | 7.0.0 |

#### ListResult

| Prop        | Type       | Description                                                                                    | Since |
| ----------- | ---------- | ---------------------------------------------------------------------------------------------- | ----- |
| **`files`** | `string[]` | The names of the files in the directory. The names are relative to the `path` that was listed. | 7.0.0 |

#### ListOptions

| Prop       | Type     | Description                                                                | Since |
| ---------- | -------- | -------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path to list files from. If not specified, the root path will be used. | 7.0.0 |

#### ReadResult

| Prop       | Type     | Description              | Since |
| ---------- | -------- | ------------------------ | ----- |
| **`data`** | `string` | The content of the file. | 7.0.0 |

#### ReadOptions

| Prop           | Type       | Description                                | Default    | Since |
| -------------- | ---------- | ------------------------------------------ | ---------- | ----- |
| **`encoding`** | `Encoding` | The encoding to use when reading the file. | `'base64'` | 7.0.0 |
| **`path`**     | `string`   | The path to read the file from.            |            | 7.0.0 |

### Enums

#### Encoding

| Members      | Value      | Since |
| ------------ | ---------- | ----- |
| **`Base64`** | `'base64'` | 7.0.0 |
| **`Utf8`**   | `'utf8'`   | 7.0.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin provides access to files in the native app bundle and is therefore only available on Android and iOS. All plugin methods are marked as only available on Android and iOS in the [API](#api) section.

### Why does my app crash when reading large asset files?

Reading large files with the `read(...)` method can cause out of memory (OOM) issues because the entire file content is returned as a string. Instead, copy the file to the app's data directory using the `copy(...)` method and read it from there using the Fetch API, as described in the [usage example](#read-an-asset-file) above.

### How is this plugin different from the Capacitor Filesystem plugin?

The Capacitor Filesystem plugin reads and writes files in the app's filesystem directories, but it cannot access the files bundled inside the native app. The Asset Manager plugin fills this gap by copying, listing, and reading native asset files. The two plugins work well together: for example, you can generate the destination path for the `copy(...)` method using the `getUri(...)` method of the Filesystem plugin.

### Which encodings are supported when reading a file?

The `read(...)` method supports Base64 and UTF-8 encoding. If no encoding is specified, Base64 is used by default.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Select a file, directory, image, or video from the device's file system or gallery.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Zip and unzip files and directories with support for encryption.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/asset-manager/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/asset-manager/LICENSE).

# Capacitor Audio Player Plugin

Capacitor plugin to play audio with background support.

## Features

The Capacitor Audio Player plugin is one of the most complete audio playback solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🌙 **Background Mode**: Play audio even when the app is in the background.
- 🎵 **Audio Focus Management**: Automatically manages audio focus on Android to pause other audio sources during playback.
- ⏯️ **Full Control**: Play, pause, resume, stop, seek, and adjust volume.
- 🔂 **Loop Support**: Loop audio playback for continuous sound.
- 📋 **Playlist Mode**: Play multiple tracks sequentially with native track advancement, even in the background.
- 🎛️ **Media Session**: Control the playback from the system's media controls (e.g. notification and lock screen), even while the app is in the background.
- ⏪ **Seek Buttons**: Display seek backward and seek forward buttons with a configurable offset in the system's media controls.
- 🎨 **Customizable Icons**: Configure the media notification icons on Android to match your app's branding.
- 🔊 **Volume Control**: Precise volume control from 0-100.
- ⏩ **Playback Speed**: Adjustable playback rate with pitch preservation.
- 🗂️ **Web Assets**: Support for web asset paths alongside file URIs and remote URLs.
- 🤝 **Compatibility**: Compatible with the [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/), [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Audio Player plugin is typically used whenever an app needs to play audio, for example:

- **Music and podcast playback**: Play remote audio files and keep them playing while the app is in the background.
- **Voice message playback**: Play voice messages recorded with the [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugin in chat or support apps.
- **Sound effects**: Play short sounds from your web assets with precise volume control and looping.
- **Audiobooks and learning apps**: Let users adjust the playback speed and seek to specific positions.

## Compatibility

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

## Demo

A working example can be found here: [capawesome-team/capacitor-audio-player-demo](https://github.com/capawesome-team/capacitor-audio-player-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [How to Play Audio in the Background in a Capacitor App](https://capawesome.io/blog/how-to-play-audio-in-the-background-in-capacitor/): Native playback, lock screen media controls, and playlists that keep running.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-audio-player` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-audio-player
npx cap sync
```

### Android

#### Variables

If needed, you can define the following project variables in your app's `variables.gradle` file to change the default versions of the dependencies:

- `$androidxMedia3ExoPlayerVersion` version of `androidx.media3:media3-exoplayer` (default: `1.6.1`)
- `$androidxMedia3SessionVersion` version of `androidx.media3:media3-session` (default: `1.6.1`)

#### Media Session

If you want to use the media session integration (see the `metadata` option of the `play(...)` method), add the following service to your `AndroidManifest.xml` inside the `application` tag:

```
<service
    android:name="io.capawesome.capacitorjs.plugins.audioplayer.AudioPlayerService"
    android:exported="false"
    android:foregroundServiceType="mediaPlayback">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService" />
    </intent-filter>
</service>
```

Also, add the following permissions before or after the `application` tag:

```
<!-- Required to display the media controls in a notification. -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
```

#### Notification Icons

If you want to use custom icons in the media notification (see [Configuration](#configuration)):

1. Add your icons to `android/app/src/main/res/drawable/` (e.g., `ic_notification.png`)

1. Icons should be single-color white with transparent background for best display

1. Can use density-specific folders (`drawable-mdpi`, `drawable-hdpi`, etc.)

1. Configure the plugin in `capacitor.config.ts`:

   ```
   const config: CapacitorConfig = {
     plugins: {
       AudioPlayer: {
         smallIcon: 'ic_notification', // Matches ic_notification.png
         seekBackwardIcon: 'ic_seek_backward_20', // Matches ic_seek_backward_20.png
         seekForwardIcon: 'ic_seek_forward_20', // Matches ic_seek_forward_20.png
       },
     },
   };
   ```

1. Run: `npx cap sync`

On iOS, the playback controls on the lock screen and in the Control Center are rendered by the operating system and cannot be customized.

### iOS

#### Capabilities

If you want to play audio in the background, ensure `Background Modes` capability is enabled with `Audio, AirPlay, and Picture in Picture` in your Xcode project. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

## Configuration

| Prop                   | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Default                                                                                                           | Since |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`seekBackwardIcon`** | `string` | The name of the drawable resource to use as the icon for the seek backward button in the media notification. The button is only displayed if a seek offset has been provided (see the `seekBackwardOffset` and `seekForwardOffset` options of the `play(...)` method). The resource name should not include the `R.drawable.` prefix or file extension. For example, if you have `res/drawable/ic_seek_backward.png`, set this to `"ic_seek_backward"`. If the resource is not found, the default icon is used. **Attention:** The icon should be white pixels on a transparent background. Otherwise, a white square or circle may be displayed instead of the icon. Only available on Android. | `"media3_icon_skip_back" (Media3 built-in icon, with a number badge for an offset of 5, 10, 15 or 30 seconds)`    | 8.5.0 |
| **`seekForwardIcon`**  | `string` | The name of the drawable resource to use as the icon for the seek forward button in the media notification. The button is only displayed if a seek offset has been provided (see the `seekBackwardOffset` and `seekForwardOffset` options of the `play(...)` method). The resource name should not include the `R.drawable.` prefix or file extension. For example, if you have `res/drawable/ic_seek_forward.png`, set this to `"ic_seek_forward"`. If the resource is not found, the default icon is used. **Attention:** The icon should be white pixels on a transparent background. Otherwise, a white square or circle may be displayed instead of the icon. Only available on Android.    | `"media3_icon_skip_forward" (Media3 built-in icon, with a number badge for an offset of 5, 10, 15 or 30 seconds)` | 8.5.0 |
| **`smallIcon`**        | `string` | The name of the drawable resource to use as the small icon in the media notification. The resource name should not include the `R.drawable.` prefix or file extension. For example, if you have `res/drawable/ic_notification.png`, set this to `"ic_notification"`. If the resource is not found, the default icon is used. **Attention:** The icon should be white pixels on a transparent background. Otherwise, a white square or circle may be displayed instead of the icon. Only available on Android.                                                                                                                                                                                    | `"media3_notification_small_icon" (Media3 built-in icon)`                                                         | 8.5.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "AudioPlayer": {
      "seekBackwardIcon": "ic_seek_backward",
      "seekForwardIcon": "ic_seek_forward",
      "smallIcon": "ic_notification"
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome-team/capacitor-audio-player" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    AudioPlayer: {
      seekBackwardIcon: "ic_seek_backward",
      seekForwardIcon: "ic_seek_forward",
      smallIcon: "ic_notification",
    },
  },
};

export default config;
```

## Usage

The following examples show how to play audio from web assets, remote URLs, the file system, or a blob, how to play playlists, and how to control, seek, adjust the volume of, and inspect the playback.

### Play an audio file from your web assets or a remote URL

Use the `src` option to play a web asset or a remote URL. Both are supported on all platforms:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const playFromWebAsset = async () => {
  await AudioPlayer.play({ 
    src: '/assets/audio.mp3', 
    loop: false, 
    volume: 100, 
    position: 0 
  });
};
```

### Play an audio file from the file system

Use the `uri` option to play a file from the device's file system, for example one retrieved with the Capacitor Filesystem plugin. This option is only available on Android and iOS:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
import { Filesystem, FilesystemDirectory } from '@capacitor/filesystem';

const playFromNativeFile = async () => {
  const { uri } = await Filesystem.getUri({
    directory: FilesystemDirectory.Documents,
    path: 'audio.mp3',
  });
  await AudioPlayer.play({ uri, loop: false, volume: 100, position: 0 });
};
```

### Play an audio file from a blob

Use the `blob` option to play a `Blob` instance, for example one fetched from a server. This option is only available on Web:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const playFromBlob = async () => {
  const assetUrl = 'https://www.example.com/audio.mp3';
  const response = await fetch(assetUrl);
  const blob = await response.blob();
  await AudioPlayer.play({ blob, loop: false, volume: 100, position: 0 });
};
```

### Play a playlist

Use the `tracks` option to play multiple tracks sequentially. The next track starts automatically when the current one ends, even in the background. Use the `startIndex` option to start playback from a specific track:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const playPlaylist = async () => {
  await AudioPlayer.play({
    tracks: [
      { src: '/assets/track1.mp3' },
      { src: '/assets/track2.mp3' },
      { src: '/assets/track3.mp3' },
    ],
    startIndex: 0,
  });
};

const listenForTrackChanges = async () => {
  await AudioPlayer.addListener('trackChange', (event) => {
    console.log('Track changed to index:', event.index);
  });
};
```

### Navigate within a playlist

Skip to the next or previous track, jump to a specific track, or retrieve the index of the current track:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const skipToNextTrack = async () => {
  await AudioPlayer.skipToNextTrack();
};

const skipToPreviousTrack = async () => {
  await AudioPlayer.skipToPreviousTrack();
};

const jumpToTrack = async () => {
  await AudioPlayer.seekTo({ index: 2, position: 0 });
};

const getCurrentTrackIndex = async () => {
  const { index } = await AudioPlayer.getCurrentTrackIndex();
  console.log('Current track index:', index);
};
```

### Modify the playlist

Add tracks to the playlist or remove tracks from it while it is playing:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const addTracks = async () => {
  await AudioPlayer.addTracks({
    tracks: [{ src: '/assets/track4.mp3' }],
  });
};

const removeTrack = async () => {
  await AudioPlayer.removeTrack({ index: 0 });
};
```

### Set the repeat mode

Repeat the current track or the entire playlist:

```
import { AudioPlayer, RepeatMode } from '@capawesome-team/capacitor-audio-player';

const setRepeatMode = async () => {
  await AudioPlayer.setRepeatMode({ mode: RepeatMode.All });
};
```

### Control the playback from the system's media controls

Provide the `metadata` option to display the playback in the system's media controls (e.g. notification and lock screen). The playback can then be controlled from there, even while the app is in the background. On Android, this requires additional manifest entries (see [Installation](#installation)):

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const playWithMediaSession = async () => {
  await AudioPlayer.play({
    tracks: [
      {
        src: 'https://example.com/track1.mp3',
        metadata: {
          album: 'The Dark Side of the Moon',
          artist: 'Pink Floyd',
          artworkSource: 'https://example.com/artwork.png',
          title: 'Time',
        },
      },
      {
        src: 'https://example.com/track2.mp3',
        metadata: {
          album: 'The Dark Side of the Moon',
          artist: 'Pink Floyd',
          artworkSource: 'https://example.com/artwork.png',
          title: 'Money',
        },
      },
    ],
  });
};

const listenForPlaybackStateChanges = async () => {
  await AudioPlayer.addListener('playbackStateChanged', (event) => {
    console.log('Playback state changed to:', event.state);
  });
};
```

Provide the `seekBackwardOffset` and `seekForwardOffset` options to display seek buttons instead of the previous and next track buttons, for example for podcasts or audiobooks:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const playWithSeekButtons = async () => {
  await AudioPlayer.play({
    src: 'https://example.com/episode.mp3',
    metadata: {
      artist: 'Capawesome',
      title: 'Episode 12',
    },
    seekBackwardOffset: 15000,
    seekForwardOffset: 30000,
  });
};
```

### Pause, resume and stop the playback

Pause the playback and resume it later, or stop it entirely:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const pause = async () => {
  await AudioPlayer.pause();
};

const resume = async () => {
  await AudioPlayer.resume();
};

const stop = async () => {
  await AudioPlayer.stop();
};
```

### Seek to a specific position

Jump to a specific position in the audio playback, given in milliseconds:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const seekTo = async () => {
  await AudioPlayer.seekTo({ position: 30_000 }); // Seek to 30 seconds
};
```

### Adjust the volume

Set the volume level of the current playback session to a value between 0 and 100:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const setVolume = async () => {
  await AudioPlayer.setVolume({ volume: 50 }); // Set volume to 50%
};
```

### Get the current playback state

Retrieve the current position and duration of the playback in milliseconds, and check whether the audio is currently playing:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const getCurrentPosition = async () => {
  const { position } = await AudioPlayer.getCurrentPosition();
  console.log('Current position:', position);
};

const getDuration = async () => {
  const { duration } = await AudioPlayer.getDuration();
  console.log('Duration:', duration);
};

const isPlaying = async () => {
  const { isPlaying } = await AudioPlayer.isPlaying();
  console.log('Is playing:', isPlaying);
};
```

## API

- [`addTracks(...)`](#addtracks)
- [`getCurrentPosition()`](#getcurrentposition)
- [`getCurrentTrackIndex()`](#getcurrenttrackindex)
- [`getDuration()`](#getduration)
- [`isPlaying()`](#isplaying)
- [`pause()`](#pause)
- [`play(...)`](#play)
- [`removeTrack(...)`](#removetrack)
- [`resume()`](#resume)
- [`seekTo(...)`](#seekto)
- [`setRate(...)`](#setrate)
- [`setRepeatMode(...)`](#setrepeatmode)
- [`setVolume(...)`](#setvolume)
- [`skipToNextTrack()`](#skiptonexttrack)
- [`skipToPreviousTrack()`](#skiptoprevioustrack)
- [`stop(...)`](#stop)
- [`addListener('playbackStateChanged', ...)`](#addlistenerplaybackstatechanged-)
- [`addListener('stop', ...)`](#addlistenerstop-)
- [`addListener('trackChange', ...)`](#addlistenertrackchange-)
- [Interfaces](#interfaces)
- [Enums](#enums)

### addTracks(...)

```
addTracks(options: AddTracksOptions) => Promise<void>
```

Add tracks to the currently loaded playlist.

Only available if a playlist has been loaded via `play({ tracks })`.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AddTracksOptions` |

**Since:** 8.4.0

______________________________________________________________________

### getCurrentPosition()

```
getCurrentPosition() => Promise<GetCurrentPositionResult>
```

Get the current position of the audio playback in milliseconds.

**Returns:** `Promise<GetCurrentPositionResult>`

**Since:** 0.0.1

______________________________________________________________________

### getCurrentTrackIndex()

```
getCurrentTrackIndex() => Promise<GetCurrentTrackIndexResult>
```

Get the index of the currently playing track within the loaded playlist.

The `index` is `undefined` if no playlist is loaded (e.g. single-track playback or nothing playing).

**Returns:** `Promise<GetCurrentTrackIndexResult>`

**Since:** 8.4.0

______________________________________________________________________

### getDuration()

```
getDuration() => Promise<GetDurationResult>
```

Get the duration of the audio playback in milliseconds.

**Returns:** `Promise<GetDurationResult>`

**Since:** 0.0.1

______________________________________________________________________

### isPlaying()

```
isPlaying() => Promise<IsPlayingResult>
```

Check whether the audio is currently playing.

**Returns:** `Promise<IsPlayingResult>`

**Since:** 0.0.1

______________________________________________________________________

### pause()

```
pause() => Promise<void>
```

Pause the audio playback.

**Since:** 0.0.1

______________________________________________________________________

### play(...)

```
play(options: PlayOptions) => Promise<void>
```

Play the audio playback.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `PlayOptions` |

**Since:** 0.0.1

______________________________________________________________________

### removeTrack(...)

```
removeTrack(options: RemoveTrackOptions) => Promise<void>
```

Remove a track from the currently loaded playlist.

If the currently playing track is removed, playback continues with the track that takes its place, or stops if it was the last track.

Only available if a playlist has been loaded via `play({ tracks })`.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `RemoveTrackOptions` |

**Since:** 8.4.0

______________________________________________________________________

### resume()

```
resume() => Promise<void>
```

Resume the audio playback.

**Since:** 0.0.1

______________________________________________________________________

### seekTo(...)

```
seekTo(options: SeekToOptions) => Promise<void>
```

Seek to a specific position and/or track within the current playback.

Provide `position` to seek within the current track, `index` to jump to a different track in the currently loaded playlist, or both to do both at once. If neither is provided, the call is a no-op.

Play state is preserved: if the player was paused, it stays paused at the new location; call `resume()` afterwards to start playback.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `SeekToOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setRate(...)

```
setRate(options: SetRateOptions) => Promise<void>
```

Set the playback rate for the audio playback.

This only affects the current playback session and is not persisted.

Only available on Android, iOS and Web.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `SetRateOptions` |

**Since:** 8.2.0

______________________________________________________________________

### setRepeatMode(...)

```
setRepeatMode(options: SetRepeatModeOptions) => Promise<void>
```

Set the repeat mode for the current playback.

This only affects the current playback session and is not persisted.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetRepeatModeOptions` |

**Since:** 8.4.0

______________________________________________________________________

### setVolume(...)

```
setVolume(options: SetVolumeOptions) => Promise<void>
```

Set the volume level for the audio playback.

This only affects the current playback session and is not persisted.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetVolumeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### skipToNextTrack()

```
skipToNextTrack() => Promise<void>
```

Skip to the next track in the currently loaded playlist.

If the repeat mode is `ALL`, skipping past the last track wraps around to the first track.

Only available if a playlist has been loaded via `play({ tracks })`.

**Since:** 8.4.0

______________________________________________________________________

### skipToPreviousTrack()

```
skipToPreviousTrack() => Promise<void>
```

Skip to the previous track in the currently loaded playlist.

If the repeat mode is `ALL`, skipping before the first track wraps around to the last track.

Only available if a playlist has been loaded via `play({ tracks })`.

**Since:** 8.4.0

______________________________________________________________________

### stop(...)

```
stop(options?: StopOptions | undefined) => Promise<void>
```

Stop the audio playback.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `StopOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('playbackStateChanged', ...)

```
addListener(eventName: 'playbackStateChanged', listenerFunc: (event: PlaybackStateChangedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the playback state changes, for example when the user pauses the playback via the media controls on the lock screen.

| Param              | Type                                         |
| ------------------ | -------------------------------------------- |
| **`eventName`**    | `'playbackStateChanged'`                     |
| **`listenerFunc`** | `(event: PlaybackStateChangedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.4.0

______________________________________________________________________

### addListener('stop', ...)

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

Called when the audio has stopped playing.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'stop'`     |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.2

______________________________________________________________________

### addListener('trackChange', ...)

```
addListener(eventName: 'trackChange', listenerFunc: (event: TrackChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the current track changes during playlist playback.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'trackChange'`                     |
| **`listenerFunc`** | `(event: TrackChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.4.0

______________________________________________________________________

### Interfaces

#### AddTracksOptions

| Prop         | Type           | Description                                                                                                           | Since |
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`index`**  | `number`       | The 0-based index at which to insert the tracks. If not provided, the tracks are appended to the end of the playlist. | 8.4.0 |
| **`tracks`** | `AudioTrack[]` | The tracks to add to the playlist.                                                                                    | 8.4.0 |

#### AudioTrack

| Prop           | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                         | Since |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`blob`**     | `Blob`          | The audio file to play. Only available on Web.                                                                                                                                                                                                                                                                                                                                                                                                      | 8.4.0 |
| **`metadata`** | `TrackMetadata` | The metadata of the track, displayed in the system's media controls (e.g. notification and lock screen). Providing metadata activates the media session integration so that the playback can be controlled from the system's media controls, even while the app is in the background. On Android, this requires additional manifest entries. See the [documentation](https://capawesome.io/docs/sdks/capacitor/audio-player/) for more information. | 8.4.0 |
| **`src`**      | `string`        | The path to the web asset file or a remote URL. Both web assets and remote URLs are supported on all platforms.                                                                                                                                                                                                                                                                                                                                     | 8.4.0 |
| **`uri`**      | `string`        | The URI or path of the audio file to play. Only available on Android and iOS.                                                                                                                                                                                                                                                                                                                                                                       | 8.4.0 |

#### TrackMetadata

| Prop                | Type     | Description                                                                                                                      | Since |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`album`**         | `string` | The album of the track.                                                                                                          | 8.4.0 |
| **`artist`**        | `string` | The artist of the track.                                                                                                         | 8.4.0 |
| **`artworkSource`** | `string` | The source of the artwork of the track, displayed in the system's media controls. Both web assets and remote URLs are supported. | 8.4.0 |
| **`title`**         | `string` | The title of the track.                                                                                                          | 8.4.0 |

#### GetCurrentPositionResult

| Prop           | Type     | Description                                                 | Since |
| -------------- | -------- | ----------------------------------------------------------- | ----- |
| **`position`** | `number` | The current position of the audio playback in milliseconds. | 0.0.1 |

#### GetCurrentTrackIndexResult

| Prop        | Type     | Description                                                                                                        | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
| **`index`** | `number` | The 0-based index of the currently playing track within the loaded playlist. `undefined` if no playlist is loaded. | 8.4.0 |

#### GetDurationResult

| Prop           | Type     | Description                                         | Since |
| -------------- | -------- | --------------------------------------------------- | ----- |
| **`duration`** | `number` | The duration of the audio playback in milliseconds. | 0.0.1 |

#### IsPlayingResult

| Prop            | Type      | Description                             | Since |
| --------------- | --------- | --------------------------------------- | ----- |
| **`isPlaying`** | `boolean` | Whether the audio is currently playing. | 0.0.1 |

#### PlayOptions

| Prop                     | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Default | Since |
| ------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`blob`**               | `Blob`          | The audio file to play. If both `blob` and `src` are provided, `blob` takes priority. Only available on Web.                                                                                                                                                                                                                                                                                                                                                                                          |         | 0.0.1 |
| **`loop`**               | `boolean`       | Whether to loop the audio playback. This option is ignored when `tracks` is provided.                                                                                                                                                                                                                                                                                                                                                                                                                 |         | 0.0.1 |
| **`metadata`**           | `TrackMetadata` | The metadata of the track, displayed in the system's media controls (e.g. notification and lock screen). Providing metadata activates the media session integration so that the playback can be controlled from the system's media controls, even while the app is in the background. On Android, this requires additional manifest entries. See the [documentation](https://capawesome.io/docs/sdks/capacitor/audio-player/) for more information. This option is ignored when `tracks` is provided. |         | 8.4.0 |
| **`position`**           | `number`        | The position to start playback from (in milliseconds).                                                                                                                                                                                                                                                                                                                                                                                                                                                |         | 0.0.1 |
| **`rate`**               | `number`        | The playback rate to use. Values between 0.5 and 2.0 are recommended. Other values may not be supported on all devices. Must be greater than `0`. Only available on Android, iOS and Web.                                                                                                                                                                                                                                                                                                             | `1.0`   | 8.2.0 |
| **`seekBackwardOffset`** | `number`        | The offset in milliseconds for the seek backward button in the system's media controls. If provided, the seek backward button is displayed instead of the previous track button, since the system's media controls only have one slot on each side of the play button. Must be greater than `0`. Only applies if the media session is active (see the `metadata` option).                                                                                                                             |         | 8.5.0 |
| **`seekForwardOffset`**  | `number`        | The offset in milliseconds for the seek forward button in the system's media controls. If provided, the seek forward button is displayed instead of the next track button, since the system's media controls only have one slot on each side of the play button. Must be greater than `0`. Only applies if the media session is active (see the `metadata` option).                                                                                                                                   |         | 8.5.0 |
| **`startIndex`**         | `number`        | The 0-based index of the track to start playback from. Only meaningful when `tracks` is provided.                                                                                                                                                                                                                                                                                                                                                                                                     | `0`     | 8.4.0 |
| **`tracks`**             | `AudioTrack[]`  | A list of audio tracks to play sequentially. When provided, `blob`, `src`, and `uri` are ignored.                                                                                                                                                                                                                                                                                                                                                                                                     |         | 8.4.0 |
| **`src`**                | `string`        | The path to the web asset file to play. If both `blob` and `src` are provided, `blob` takes priority. If both `uri` and `src` are provided, `uri` takes priority. Both web assets and remote URLs are supported on all platforms.                                                                                                                                                                                                                                                                     |         | 0.1.2 |
| **`uri`**                | `string`        | The URI or path of the audio file to play. If both `uri` and `src` are provided, `uri` takes priority. Only available on Android and iOS.                                                                                                                                                                                                                                                                                                                                                             |         | 0.0.1 |
| **`volume`**             | `number`        | The volume level to set (0-100).                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `100`   | 0.0.1 |

#### RemoveTrackOptions

| Prop        | Type     | Description                                                 | Since |
| ----------- | -------- | ----------------------------------------------------------- | ----- |
| **`index`** | `number` | The 0-based index of the track to remove from the playlist. | 8.4.0 |

#### SeekToOptions

| Prop           | Type     | Description                                                                                                                                             | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`index`**    | `number` | The 0-based index of the track to jump to within the currently loaded playlist. Only meaningful when a playlist has been loaded via `play({ tracks })`. | 8.4.0 |
| **`position`** | `number` | The position to seek to (in milliseconds). When `index` is also provided, this is the position within the target track.                                 | 0.0.1 |

#### SetRateOptions

| Prop       | Type     | Description                                                                                                                                       | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`rate`** | `number` | The playback rate to set. Values between 0.5 and 2.0 are recommended. Other values may not be supported on all devices. Must be greater than `0`. | 8.2.0 |

#### SetRepeatModeOptions

| Prop       | Type         | Description             | Since |
| ---------- | ------------ | ----------------------- | ----- |
| **`mode`** | `RepeatMode` | The repeat mode to set. | 8.4.0 |

#### SetVolumeOptions

| Prop         | Type     | Description                      | Since |
| ------------ | -------- | -------------------------------- | ----- |
| **`volume`** | `number` | The volume level to set (0-100). | 0.0.1 |

#### StopOptions

| Prop                         | Type      | Description                                                                                                                                                                                                                                                           | Default | Since |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deactivateAudioSession`** | `boolean` | Whether to deactivate the audio session when stopping playback. Set to `false` if you intend to call `play()` again shortly after stopping, to avoid `CoreMediaErrorDomain -16042` errors on iOS or audio focus issues on Android. Only available on Android and iOS. | `true`  | 8.3.0 |

#### PluginListenerHandle

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

#### PlaybackStateChangedEvent

| Prop        | Type            | Description             | Since |
| ----------- | --------------- | ----------------------- | ----- |
| **`state`** | `PlaybackState` | The new playback state. | 8.4.0 |

#### TrackChangeEvent

| Prop        | Type     | Description                                 | Since |
| ----------- | -------- | ------------------------------------------- | ----- |
| **`index`** | `number` | The 0-based index of the new current track. | 8.4.0 |

### Enums

#### RepeatMode

| Members    | Value    | Description                 | Since |
| ---------- | -------- | --------------------------- | ----- |
| **`All`**  | `'ALL'`  | Repeat the entire playlist. | 8.4.0 |
| **`None`** | `'NONE'` | Do not repeat.              | 8.4.0 |
| **`One`**  | `'ONE'`  | Repeat the current track.   | 8.4.0 |

#### PlaybackState

| Members       | Value       | Description              | Since |
| ------------- | ----------- | ------------------------ | ----- |
| **`Paused`**  | `'PAUSED'`  | The playback is paused.  | 8.4.0 |
| **`Playing`** | `'PLAYING'` | The playback is playing. | 8.4.0 |
| **`Stopped`** | `'STOPPED'` | The playback is stopped. | 8.4.0 |

## Troubleshooting

##### `CoreMediaErrorDomain -16042` error on iOS when calling `play()` after `stop()`

When `stop()` is called, the audio session is deactivated by default. If `play()` is called shortly after, `AVAudioSession.setActive(true)` can fail with `CoreMediaErrorDomain -16042`, breaking all subsequent playback. To avoid this, set `deactivateAudioSession` to `false` in the `stop()` options:

```
await AudioPlayer.stop({ deactivateAudioSession: false });
```

## FAQ

### Can I play audio while the app is in the background?

Yes, the plugin supports background playback. On iOS, you need to enable the `Background Modes` capability with `Audio, AirPlay, and Picture in Picture` in your Xcode project, as described in the [Installation](#installation) section.

### Which audio sources can I play?

You can play web assets and remote URLs via the `src` option on all platforms. On Android and iOS, you can also play files from the device's file system via the `uri` option. On Web, you can play `Blob` instances via the `blob` option. See the [Usage](#usage) section for examples.

### How can I change the playback speed?

Use the `rate` option of the `play(...)` method or call `setRate(...)` during playback. Values between 0.5 and 2.0 are recommended, as other values may not be supported on all devices. The playback rate is adjusted with pitch preservation and is available on Android (SDK 23+), iOS and Web.

### Why does playback fail with a CoreMediaErrorDomain -16042 error on iOS?

This can happen when `play()` is called shortly after `stop()`, because the audio session is deactivated by default when stopping. Set the `deactivateAudioSession` option of the `stop(...)` method to `false` if you intend to play audio again shortly after stopping. See the [Troubleshooting](#troubleshooting) section for more details.

### Can I use this plugin together with other audio plugins?

Yes, the plugin is compatible with the [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/), [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins. For example, you can play back a recording created with the Audio Recorder plugin. However, combining it with the [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/) plugin is not recommended. Use the built-in media session integration (see the `metadata` option of the `play(...)` method) instead, which handles the media controls natively, even when the web view is suspended while the app is in the background.

### How can I display seek buttons in the system's media controls?

Provide the `seekBackwardOffset` and `seekForwardOffset` options of the `play(...)` method with the desired offsets in milliseconds. The seek buttons are displayed instead of the previous and next track buttons, since the system's media controls only have one slot on each side of the play button. The options belong to the playback, so a playlist started without them displays the previous and next track buttons again. See the [Usage](#usage) section for an example.

### Can I customize the notification icons on Android?

Yes, use the `smallIcon`, `seekBackwardIcon` and `seekForwardIcon` configuration options to set the name of a drawable resource from your app's `res/drawable` directory. The icons should be single-color white with a transparent background for the best display. If a resource is not found, the default icon is used. The play, pause, previous track and next track buttons cannot be customized, as they are rendered by the operating system. See the [Configuration](#configuration) section for details.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone.
- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session.
- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons.
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text with voice selection, pitch, and rate control.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/LICENSE).

# Capacitor Audio Recorder Plugin

Capacitor plugin for seamless audio recording using the device's microphone. Supports Android, iOS, and Web with advanced features and high performance.

## Features

The Capacitor Audio Recorder plugin is one of the most advanced audio recording solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- ⏯️ **Full Control**: Start, pause, resume, cancel and stop recording.
- 🚀 **Performance**: Record long audio sessions without any performance issues.
- 🔑 **Permissions**: Check and request microphone permissions.
- 🔊 **Events**: Listen for events like `recordingError`, `recordingPaused` or `recordingStopped`.
- 🌙 **Background Mode**: Record audio even when the app is in the background.
- 🤝 **Compatibility**: Compatible with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/), [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Audio Recorder plugin is typically used whenever an app needs to capture audio with the device's microphone, for example:

- **Voice messages**: Record voice messages in chat apps and play them back with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) plugin.
- **Voice notes and memos**: Let users record notes with full control to pause, resume, or cancel the recording.
- **Dictation and transcription**: Capture spoken audio that is later transcribed, for example by a server-side speech-to-text service.
- **Interviews and long sessions**: Record long audio sessions without performance issues, even while the app is in the background.

## Compatibility

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

## Guides

- [Announcing the Capacitor Audio Recorder Plugin](https://capawesome.io/blog/announcing-the-capacitor-audio-recorder-plugin/)
- [Exploring the Capacitor Audio Recorder API](https://capawesome.io/blog/exploring-the-capacitor-audio-recorder-api/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-audio-recorder` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-audio-recorder
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Capabilities

If you want to record audio in the background, ensure `Background Modes` capability is enabled with `Audio, AirPlay, and Picture in Picture` in your Xcode project. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

#### Privacy Descriptions

Add the `NSMicrophoneUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts:

```
<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to manage permissions, start a recording, save it to a custom location, stop and play it back, pause, resume or cancel it, read the recording status, and listen for recording events.

### Check and request permissions

Recording requires the microphone permission. Check and request it before starting a recording:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const checkPermissions = async () => {
  const { recordAudio } = await AudioRecorder.checkPermissions();
  console.log('Record audio permission:', recordAudio);
};

const requestPermissions = async () => {
  const { recordAudio } = await AudioRecorder.requestPermissions();
  console.log('Record audio permission:', recordAudio);
};
```

### Start a recording

Start recording audio in AAC format. You can optionally configure the bitrate and sample rate (Android and iOS) as well as the audio session category options and mode (iOS only):

```
import { AudioRecorder, AudioSessionCategoryOption, AudioSessionMode } from '@capawesome-team/capacitor-audio-recorder';

const startRecording = async () => {
  await AudioRecorder.startRecording({
    audioSessionCategoryOptions: [AudioSessionCategoryOption.DuckOthers],
    audioSessionMode: AudioSessionMode.Measurement,
    bitRate: 192000,
    sampleRate: 44100
  });
};
```

### Save the recording to a custom location

By default, the recording is saved to a temporary location in the cache directory. On Android and iOS, use the `uri` option to save it to a custom location instead, for example one generated with the Capacitor Filesystem plugin:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { Directory, Filesystem } from '@capacitor/filesystem';

const startRecordingToCustomLocation = async () => {
  const { uri } = await Filesystem.getUri({
    directory: Directory.Data,
    path: 'recordings/my-recording.aac'
  });
  await AudioRecorder.startRecording({ uri });
};
```

### Stop the recording and play it back

Stop the recording to receive the recorded audio as a `Blob` (Web) or URI (Android and iOS), which you can then play back, for example with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) plugin:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const stopRecording = async () => {
  // Stop recording and get the audio blob or URI
  const { blob, uri } = await AudioRecorder.stopRecording();
  // Play the audio
  if (blob) {
    // Only available on Web
    await AudioPlayer.play({ blob });
  } else if (uri) {
    // Only available on Android and iOS
    await AudioPlayer.play({ uri });
  }
};
```

### Pause, resume or cancel the recording

Pause a running recording and resume it later, or cancel it to discard the recorded audio. Pausing and resuming is only available on Android (SDK 24+), iOS and Web:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const pauseRecording = async () => {
  await AudioRecorder.pauseRecording();
};

const resumeRecording = async () => {
  await AudioRecorder.resumeRecording();
};

const cancelRecording = async () => {
  await AudioRecorder.cancelRecording();
};
```

### Get the current recording status

Check whether a recording is currently inactive, active or paused:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const getRecordingStatus = async () => {
  const { status } = await AudioRecorder.getRecordingStatus();
  console.log('Recording status:', status);
};
```

### Listen for recording events

Get notified when the recording is paused (e.g. when it is interrupted by a phone call), when it is stopped, or when an error occurs. The `recordingError` event is only available on iOS:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const addRecordingErrorListener = async () => {
  await AudioRecorder.addListener('recordingError', (event) => {
    console.error('Recording error:', event.message);
  });
};

const addRecordingPausedListener = async () => {
  await AudioRecorder.addListener('recordingPaused', () => {
    console.log('Recording paused');
  });
};

const addRecordingStoppedListener = async () => {
  await AudioRecorder.addListener('recordingStopped', (event) => {
    console.log('Recording stopped:', event.uri);
  });
};
```

## API

- [`cancelRecording()`](#cancelrecording)
- [`getRecordingStatus()`](#getrecordingstatus)
- [`pauseRecording()`](#pauserecording)
- [`resumeRecording()`](#resumerecording)
- [`startRecording(...)`](#startrecording)
- [`stopRecording()`](#stoprecording)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('recordingError', ...)`](#addlistenerrecordingerror-)
- [`addListener('recordingPaused', ...)`](#addlistenerrecordingpaused-)
- [`addListener('recordingResumed', ...)`](#addlistenerrecordingresumed-)
- [`addListener('recordingStopped', ...)`](#addlistenerrecordingstopped-)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### cancelRecording()

```
cancelRecording() => Promise<void>
```

Cancel the recording.

**Since:** 7.0.0

______________________________________________________________________

### getRecordingStatus()

```
getRecordingStatus() => Promise<GetRecordingStatusResult>
```

Check if the device supports audio recording.

**Returns:** `Promise<GetRecordingStatusResult>`

**Since:** 7.0.0

______________________________________________________________________

### pauseRecording()

```
pauseRecording() => Promise<void>
```

Pause the recording.

This method is only available on Android (SDK 24+), iOS and Web.

**Since:** 7.0.0

______________________________________________________________________

### resumeRecording()

```
resumeRecording() => Promise<void>
```

Resume the recording.

This method is only available on Android (SDK 24+), iOS and Web.

**Since:** 7.0.0

______________________________________________________________________

### startRecording(...)

```
startRecording(options?: StartRecordingOptions | undefined) => Promise<void>
```

Start recording audio in AAC format.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `StartRecordingOptions` |

**Since:** 7.0.0

______________________________________________________________________

### stopRecording()

```
stopRecording() => Promise<StopRecordingResult>
```

Stop recording audio.

**Returns:** `Promise<StopRecordingResult>`

**Since:** 7.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for audio recording.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permissions for audio recording.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### addListener('recordingError', ...)

```
addListener(eventName: 'recordingError', listenerFunc: (event: RecordingErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during recording. The recording will be cancelled.

Only available on iOS.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'recordingError'`                     |
| **`listenerFunc`** | `(event: RecordingErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.0.0

______________________________________________________________________

### addListener('recordingPaused', ...)

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

Called when the recording is paused (e.g. when the recording is interrupted by a phone call).

| Param              | Type                |
| ------------------ | ------------------- |
| **`eventName`**    | `'recordingPaused'` |
| **`listenerFunc`** | `() => void`        |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.1.0

______________________________________________________________________

### addListener('recordingResumed', ...)

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

Called when the recording is resumed (e.g. after an audio session interruption ends, when `autoResumeAfterInterruption` is enabled).

| Param              | Type                 |
| ------------------ | -------------------- |
| **`eventName`**    | `'recordingResumed'` |
| **`listenerFunc`** | `() => void`         |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('recordingStopped', ...)

```
addListener(eventName: 'recordingStopped', listenerFunc: (event: RecordingStoppedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the recording is stopped.

**Note**: This will not be called if the recording is cancelled or paused or if an error occurs.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'recordingStopped'`                     |
| **`listenerFunc`** | `(event: RecordingStoppedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### GetRecordingStatusResult

| Prop         | Type              | Description                   | Default                    | Since |
| ------------ | ----------------- | ----------------------------- | -------------------------- | ----- |
| **`status`** | `RecordingStatus` | The current recording status. | `RecordingStatus.Inactive` | 7.0.0 |

#### StartRecordingOptions

| Prop                              | Type                           | Description                                                                                                                                                                                                                                                                 | Default                    | Since |
| --------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----- |
| **`autoResumeAfterInterruption`** | `boolean`                      | Whether the recording should automatically resume after an audio session interruption ends (e.g. after a phone call). The system only resumes the recording if it indicates that resuming is appropriate. Only available on iOS.                                            | `false`                    | 8.2.0 |
| **`audioSessionCategoryOptions`** | `AudioSessionCategoryOption[]` | The audio session category options for recording. Only available on iOS.                                                                                                                                                                                                    | `['duckOthers']`           | 7.5.0 |
| **`audioSessionMode`**            | `AudioSessionMode`             | The audio session mode for recording. Only available on iOS.                                                                                                                                                                                                                | `AudioSessionMode.Default` | 7.4.0 |
| **`bitRate`**                     | `number`                       | The audio bitrate in bytes per second. This option is only available on Android and iOS.                                                                                                                                                                                    | `192000`                   | 7.2.0 |
| **`sampleRate`**                  | `number`                       | The audio sample rate in Hz. This option is only available on Android and iOS.                                                                                                                                                                                              | `44100`                    | 7.1.0 |
| **`uri`**                         | `string`                       | The URI where the recorded audio should be saved. If not provided, the recording is saved to a temporary location in the cache directory. **Tip:** Generate this path using the `getUri(...)` method of the Capacitor Filesystem plugin. Only available on Android and iOS. |                            | 8.1.0 |

#### StopRecordingResult

| Prop           | Type     | Description                                                       | Since |
| -------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`blob`**     | `Blob`   | The recorded audio as a Blob. Only available on Web.              | 7.0.0 |
| **`duration`** | `number` | The duration of the recorded audio in milliseconds.               | 7.1.0 |
| **`uri`**      | `string` | The URI of the recorded audio. Only available on Android and iOS. | 7.0.0 |

#### PermissionStatus

| Prop              | Type              | Description                               | Since |
| ----------------- | ----------------- | ----------------------------------------- | ----- |
| **`recordAudio`** | `PermissionState` | The permission state for audio recording. | 7.0.0 |

#### PluginListenerHandle

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

#### RecordingErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 7.0.0 |

#### RecordingStoppedEvent

| Prop           | Type     | Description                                                       | Since |
| -------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`blob`**     | `Blob`   | The recorded audio as a Blob. Only available on Web.              | 7.0.0 |
| **`duration`** | `number` | The duration of the recorded audio in milliseconds.               | 7.1.0 |
| **`uri`**      | `string` | The URI of the recorded audio. Only available on Android and iOS. | 7.0.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### RecordingStatus

| Members         | Value         | Description                | Since |
| --------------- | ------------- | -------------------------- | ----- |
| **`Inactive`**  | `'INACTIVE'`  | The recording is inactive. | 7.0.0 |
| **`Recording`** | `'RECORDING'` | The recording is active.   | 7.0.0 |
| **`Paused`**    | `'PAUSED'`    | The recording is paused.   | 7.0.0 |

#### AudioSessionCategoryOption

| Members                                    | Value                                          | Description                                                                                                                | Since |
| ------------------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`AllowAirPlay`**                         | `'ALLOW_AIR_PLAY'`                             | Option to stream audio from this session to AirPlay devices.                                                               | 7.5.0 |
| **`AllowBluetooth`**                       | `'ALLOW_BLUETOOTH'`                            | Option to make Bluetooth hands-free devices appears as available input routes.                                             | 7.5.0 |
| **`AllowBluetoothA2DP`**                   | `'ALLOW_BLUETOOTH_A2DP'`                       | Option to stream audio from this session to Bluetooth devices that support the Advanced Audio Distribution Profile (A2DP). | 7.5.0 |
| **`DefaultToSpeaker`**                     | `'DEFAULT_TO_SPEAKER'`                         | Option to make audio from this session to default to the built-in speaker instead of the receiver.                         | 7.5.0 |
| **`DuckOthers`**                           | `'DUCK_OTHERS'`                                | Option to reduce the audio volume of other active sessions when audio from this session is in play.                        | 7.5.0 |
| **`InterruptSpokenAudioAndMixWithOthers`** | `'INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS'` | Option to pause spoken audio of other sessions when audio from this session is in play.                                    | 7.5.0 |
| **`MixWithOthers`**                        | `'MIX_WITH_OTHERS'`                            | Option to mix audio with audio from other active sessions in other apps.                                                   | 7.5.0 |
| **`overrideMutedMicrophoneInterruption`**  | `'OVERRIDE_MUTED_MICROPHONE_INTERRUPTION'`     | Option that indicates if the system interrupts the audio session when it mutes the built-in microphone.                    | 7.5.0 |

#### AudioSessionMode

| Members              | Value               | Description                                                                   | Since |
| -------------------- | ------------------- | ----------------------------------------------------------------------------- | ----- |
| **`Default`**        | `'DEFAULT'`         | Default mode that doesn't enable additional audio session features.           | 7.4.0 |
| **`GameChat`**       | `'GAME_CHAT'`       | Mode for chat communication over VoIP or internet, optimized for low latency. | 7.4.0 |
| **`Measurement`**    | `'MEASUREMENT'`     | Mode for high-quality measurement recordings with maximum dynamic range.      | 7.4.0 |
| **`SpokenAudio`**    | `'SPOKEN_AUDIO'`    | Mode for speech recording and transcription with optimized voice processing.  | 7.4.0 |
| **`VideoChat`**      | `'VIDEO_CHAT'`      | Mode for two-way video chat communications.                                   | 7.4.0 |
| **`VideoRecording`** | `'VIDEO_RECORDING'` | Mode for recording video content with high-quality audio.                     | 7.4.0 |
| **`VoiceChat`**      | `'VOICE_CHAT'`      | Mode for voice chat communications.                                           | 7.4.0 |

## Troubleshooting

##### `recordingError` event fires with "An unknown error occurred." and the recording file is 0 bytes

This typically happens when an incompatible combination of `bitRate` and `sampleRate` is passed to `startRecording(...)`. The AAC encoder accepts the settings without error at start, but silently fails to encode, producing an empty file and triggering the `recordingError` event on stop.

For example, requesting `bitRate: 256000` with `sampleRate: 16000` (mono AAC) is invalid, because the requested bitrate is far higher than what the encoder can produce from the given sample rate. As a rule of thumb, AAC requires roughly `bitRate <= sampleRate * channels * 6`. Either lower the `bitRate` or raise the `sampleRate` (the default is `44100` Hz, which works with bitrates up to ~256 kbps):

```
await AudioRecorder.startRecording({
  bitRate: 256_000,
  sampleRate: 44_100,
});
```

## FAQ

### Which audio format is used for recordings?

The plugin records audio in AAC format. You can configure the bitrate (default: 192000 bytes per second) and sample rate (default: 44100 Hz) via the options of the `startRecording(...)` method on Android and iOS.

### Can I record audio while the app is in the background?

Yes, the plugin supports background recording. On iOS, you need to enable the `Background Modes` capability with `Audio, AirPlay, and Picture in Picture` in your Xcode project, as described in the [Installation](#installation) section.

### What permissions are required to record audio?

The plugin needs access to the device's microphone, which you can check and request using the `checkPermissions()` and `requestPermissions()` methods. On iOS, you also need to add the `NSMicrophoneUsageDescription` key to your `Info.plist` file as described in the [Installation](#installation) section.

### Why is my recording file empty?

This typically happens when an incompatible combination of `bitRate` and `sampleRate` is passed to `startRecording(...)`. The AAC encoder silently fails to encode, producing an empty file and triggering the `recordingError` event. Either lower the `bitRate` or raise the `sampleRate`. See the [Troubleshooting](#troubleshooting) section for more details.

### Where is the recorded audio saved?

By default, the recording is saved to a temporary location in the cache directory on Android and iOS, and its URI is returned by the `stopRecording()` method. You can save the recording to a custom location instead by passing the `uri` option to `startRecording(...)`. On Web, the recorded audio is returned as a `Blob`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play back recorded audio with background support.
- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/): Transcribe speech into text (speech-to-text).
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text (text-to-speech).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-recorder/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-recorder/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-recorder/LICENSE).

# Capacitor Audio Session Plugin

Capacitor plugin to configure and observe the iOS [audio session](https://developer.apple.com/documentation/avfaudio/avaudiosession).

## Features

The Capacitor Audio Session plugin is one of the most complete audio session management solutions for Capacitor apps. Here are some of the key features:

- 🎛️ **Configuration**: Set the audio session category, mode and options.
- 🔌 **Activation**: Activate and deactivate the audio session.
- 🔊 **Output routing**: Read the current audio outputs and override the output port.
- 📡 **Events**: Observe interruption and route change events.
- 🤝 **Compatibility**: Works alongside the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) and [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Audio Session plugin is typically used whenever an app needs fine-grained control over how audio behaves on iOS, for example:

- **Media playback apps**: Configure the `playback` category so audio keeps playing while other apps are silenced.
- **Voice and video chat**: Switch between the receiver and the built-in speaker using the output override.
- **Mixing with other apps**: Let your audio play alongside (or duck) audio from other apps using the category options.
- **Handling phone calls**: Pause playback when the session is interrupted and resume it when the interruption ends.
- **Headphone awareness**: React when headphones or Bluetooth devices are plugged in or out by observing route changes.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-audio-session` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-audio-session
npx cap sync
```

This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to configure the audio session, activate or deactivate it, read the current audio outputs, route playback to the built-in speaker, listen for interruptions and route changes, and remove all listeners.

### Configure the audio session

Set the audio session category, mode and options, for example for movie playback that interrupts audio from other apps. All methods of this plugin are only available on iOS:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const configure = async () => {
  await AudioSession.configure({
    category: 'playback',
    mode: 'moviePlayback',
    options: {
      mixWithOthers: false,
    },
  });
};
```

### Activate or deactivate the audio session

Activate the audio session before playing or recording audio, and deactivate it when you are done so that other apps can resume their playback:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const setActive = async () => {
  await AudioSession.setActive({ active: true });
};
```

### Read the current audio outputs

Get the audio outputs of the current audio route, for example to check whether headphones are connected:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const getCurrentOutputs = async () => {
  const { outputs } = await AudioSession.getCurrentOutputs();
  return outputs;
};
```

### Route playback to the built-in speaker

Override the audio output port that is used for playback, for example to switch from the receiver to the loudspeaker during a call:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const overrideOutput = async () => {
  await AudioSession.overrideOutput({ type: 'speaker' });
};
```

### Listen for interruptions

Get notified when the audio session is interrupted, e.g. by an incoming phone call. The `shouldResume` flag tells you whether playback should resume after the interruption ended:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const addInterruptionListener = async () => {
  await AudioSession.addListener('interruption', event => {
    console.log('Interruption:', event.type, event.shouldResume);
  });
};
```

### Listen for route changes

Get notified when the audio route changes, e.g. when headphones are plugged in or out:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

const addRouteChangeListener = async () => {
  await AudioSession.addListener('routeChange', event => {
    console.log('Route change:', event.reason, event.outputs);
  });
};
```

### Remove all listeners

Remove all listeners that were registered for this plugin:

```
import { AudioSession } from '@capawesome/capacitor-audio-session';

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

## API

- [`configure(...)`](#configure)
- [`getCurrentOutputs()`](#getcurrentoutputs)
- [`overrideOutput(...)`](#overrideoutput)
- [`setActive(...)`](#setactive)
- [`addListener('interruption', ...)`](#addlistenerinterruption-)
- [`addListener('routeChange', ...)`](#addlistenerroutechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### configure(...)

```
configure(options: ConfigureOptions) => Promise<void>
```

Configure the audio session category, mode and options.

Only available on iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `ConfigureOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getCurrentOutputs()

```
getCurrentOutputs() => Promise<GetCurrentOutputsResult>
```

Get the audio outputs of the current audio route.

Only available on iOS.

**Returns:** `Promise<GetCurrentOutputsResult>`

**Since:** 0.1.0

______________________________________________________________________

### overrideOutput(...)

```
overrideOutput(options: OverrideOutputOptions) => Promise<void>
```

Override the audio output port that is used for playback.

Only available on iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `OverrideOutputOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setActive(...)

```
setActive(options: SetActiveOptions) => Promise<void>
```

Activate or deactivate the audio session.

Only available on iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetActiveOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('interruption', ...)

```
addListener(eventName: 'interruption', listenerFunc: (event: InterruptionEvent) => void) => Promise<PluginListenerHandle>
```

Called when the audio session is interrupted, e.g. by an incoming phone call.

Only available on iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'interruption'`                     |
| **`listenerFunc`** | `(event: InterruptionEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('routeChange', ...)

```
addListener(eventName: 'routeChange', listenerFunc: (event: RouteChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the audio route changes, e.g. when headphones are plugged in or out.

Only available on iOS.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'routeChange'`                     |
| **`listenerFunc`** | `(event: RouteChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ConfigureOptions

| Prop           | Type                          | Description                         | Default     | Since |
| -------------- | ----------------------------- | ----------------------------------- | ----------- | ----- |
| **`category`** | `AudioSessionCategory`        | The audio session category.         |             | 0.1.0 |
| **`mode`**     | `AudioSessionMode`            | The audio session mode.             | `'default'` | 0.1.0 |
| **`options`**  | `AudioSessionCategoryOptions` | The audio session category options. |             | 0.1.0 |

#### AudioSessionCategoryOptions

| Prop                                       | Type      | Description                                                                                                                                  | Default | Since |
| ------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`allowAirPlay`**                         | `boolean` | Whether AirPlay devices can be used for output.                                                                                              | `false` | 0.1.0 |
| **`allowBluetooth`**                       | `boolean` | Whether Bluetooth hands-free devices can be used for input and output.                                                                       | `false` | 0.1.0 |
| **`allowBluetoothA2DP`**                   | `boolean` | Whether Bluetooth A2DP devices can be used for output.                                                                                       | `false` | 0.1.0 |
| **`defaultToSpeaker`**                     | `boolean` | Whether audio is routed to the built-in speaker instead of the receiver when no other audio route is connected.                              | `false` | 0.1.0 |
| **`duckOthers`**                           | `boolean` | Whether audio from other sessions is reduced in volume (ducked) while audio from this session plays.                                         | `false` | 0.1.0 |
| **`interruptSpokenAudioAndMixWithOthers`** | `boolean` | Whether audio from other sessions using the `spokenAudio` mode is interrupted and audio from this session is mixed with the remaining audio. | `false` | 0.1.0 |
| **`mixWithOthers`**                        | `boolean` | Whether audio from this session mixes with audio from other active sessions instead of interrupting them.                                    | `false` | 0.1.0 |

#### GetCurrentOutputsResult

| Prop          | Type                   | Description                                   | Since |
| ------------- | ---------------------- | --------------------------------------------- | ----- |
| **`outputs`** | `AudioSessionOutput[]` | The audio outputs of the current audio route. | 0.1.0 |

#### AudioSessionOutput

| Prop           | Type     | Description                                       | Since |
| -------------- | -------- | ------------------------------------------------- | ----- |
| **`portName`** | `string` | The human-readable name of the audio output port. | 0.1.0 |
| **`portType`** | `string` | The type of the audio output port.                | 0.1.0 |

#### OverrideOutputOptions

| Prop       | Type                 | Description                                 | Since |
| ---------- | -------------------- | ------------------------------------------- | ----- |
| **`type`** | `OverrideOutputType` | The audio output port to route playback to. | 0.1.0 |

#### SetActiveOptions

| Prop                             | Type      | Description                                                                                              | Default | Since |
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`active`**                     | `boolean` | Whether the audio session should be activated (`true`) or deactivated (`false`).                         |         | 0.1.0 |
| **`notifyOthersOnDeactivation`** | `boolean` | Whether other audio sessions are notified when this session is deactivated, so they can resume playback. | `true`  | 0.1.0 |

#### PluginListenerHandle

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

#### InterruptionEvent

| Prop               | Type               | Description                                                                                    | Since |
| ------------------ | ------------------ | ---------------------------------------------------------------------------------------------- | ----- |
| **`shouldResume`** | `boolean`          | Whether playback should resume after the interruption ended. Only `true` if `type` is `ended`. | 0.1.0 |
| **`type`**         | `InterruptionType` | The type of the interruption.                                                                  | 0.1.0 |

#### RouteChangeEvent

| Prop          | Type                   | Description                                            | Since |
| ------------- | ---------------------- | ------------------------------------------------------ | ----- |
| **`outputs`** | `AudioSessionOutput[]` | The audio outputs of the audio route after the change. | 0.1.0 |
| **`reason`**  | `RouteChangeReason`    | The reason why the audio route changed.                | 0.1.0 |

### Type Aliases

#### AudioSessionCategory

The audio session category.

`'ambient' | 'multiRoute' | 'playAndRecord' | 'playback' | 'record' | 'soloAmbient'`

#### AudioSessionMode

The audio session mode.

`'default' | 'gameChat' | 'measurement' | 'moviePlayback' | 'spokenAudio' | 'videoChat' | 'videoRecording' | 'voiceChat' | 'voicePrompt'`

#### OverrideOutputType

The audio output port to route playback to.

`'default' | 'speaker'`

#### InterruptionType

The type of an audio session interruption.

`'began' | 'ended'`

#### RouteChangeReason

The reason why the audio route changed.

`'categoryChange' | 'newDeviceAvailable' | 'noSuitableRouteForCategory' | 'oldDeviceUnavailable' | 'override' | 'routeConfigurationChange' | 'unknown' | 'wakeFromSleep'`

## Session Ownership

The audio session returned by [`AVAudioSession.sharedInstance()`](https://developer.apple.com/documentation/avfaudio/avaudiosession) is a **single, app-wide** object. This plugin gives you **manual** control over it, but so do other audio-related plugins (such as the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/), [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) and Speech Recognition plugins) and the underlying platform APIs they use.

Because the session is shared, the **last write wins**: calling `configure(...)` may override the category, mode or options that another plugin has set, and vice versa. This plugin cannot prevent that. If you combine this plugin with other audio plugins, make sure to reconfigure the session whenever you switch between playback, recording and other audio scenarios.

## FAQ

### How is this plugin different from other similar plugins?

It gives you fine-grained control over the iOS audio session through one fully typed API: set the category, mode and options, activate or deactivate the session, read the current outputs and override the output route, and observe interruption and route-change events. It documents the shared, app-wide nature of the audio session honestly, so you know exactly how it behaves alongside other audio code, and it's actively maintained against the latest Capacitor and iOS versions. If you only play a simple sound, a basic setup is enough; if you need precise session control, this plugin is designed for exactly that.

### Is this plugin available on Android or the Web?

No, this plugin is only available on iOS since it controls the iOS-specific [audio session](https://developer.apple.com/documentation/avfaudio/avaudiosession). On Android and Web, all methods reject as unimplemented, so you can safely include the plugin in a cross-platform app.

### Why are my audio session settings overridden by other plugins?

The audio session is a single, app-wide object that is shared with other audio-related plugins (such as the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) and [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugins) and the underlying platform APIs they use. The last write wins, so another plugin may override the category, mode or options you have set. Reconfigure the session whenever you switch between playback, recording and other audio scenarios. See the [Session Ownership](#session-ownership) section for more details.

### How can my app play audio without interrupting other apps?

Use the `mixWithOthers` category option when calling `configure(...)` to mix your audio with audio from other active sessions instead of interrupting them. Alternatively, use the `duckOthers` option to reduce the volume of other sessions while your audio plays.

### How do I resume playback after a phone call interrupted my app?

Add a listener for the `interruption` event. When the event's `type` is `ended` and `shouldResume` is `true`, playback should be resumed. See [Listen for interruptions](#listen-for-interruptions) for an example.

### How do I route audio to the loudspeaker?

Call `overrideOutput(...)` with the type `speaker` to route playback to the built-in speaker, and with `default` to restore the default route. If you want audio to be routed to the speaker by default when no other route is connected, use the `defaultToSpeaker` category option when calling `configure(...)`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play audio with background support.
- [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone.
- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/LICENSE).

# Capacitor Background Geolocation Plugin

Capacitor plugin for reliable background geolocation tracking on Android and iOS. Provides a first-class permissions API, a correctly plumbed Android foreground service and fine-grained tuning options.

## Features

The Capacitor Background Geolocation plugin provides everything you need for reliable location tracking, even while the app is in the background. Here are some of the key features:

- 🛰️ **Background Tracking**: Keeps receiving position updates while the app is in the background.
- 🔐 **Granular Permissions**: First-class permissions API including the two-step background location upgrade flow.
- 📍 **One-Shot Position**: Get the current position with configurable accuracy, timeout and maximum age.
- 🗄️ **Local Queue**: Persist every position in an on-device SQLite queue and read it out later, so nothing is lost while the web view is suspended.
- ☁️ **HTTP Upload**: Upload queued positions to your own server in batches with automatic retries and at-least-once delivery.
- 🧪 **Upload Testing**: Test the upload pipeline without your own server using the free [Background Geolocation Playground](https://background-geolocation-playground.capawesome.io) webpage.
- 🛠️ **Real Tuning Knobs**: Configure accuracy, distance filter and update interval.
- 🤖 **Foreground Service**: Correct Android 14+ foreground service with a fully configurable notification.
- 📡 **Provider Choice**: Fused location provider by default with an escape hatch to the platform location manager for devices without Google Play services.
- 🎯 **Full Accuracy Requests**: Request temporary full accuracy from users with reduced location accuracy on iOS.
- 🕵️ **Mock Location Detection**: Every position reports whether it was delivered by a mock location provider on Android.
- 🔋 **Battery Friendly**: Optional automatic pausing of position updates on iOS when the device is stationary.
- 🔒 **Public APIs Only**: Built exclusively on public platform APIs, so it is safe for App Review and resilient to OS updates.
- 🤝 **Compatibility**: Works hand in hand with the [Geofences](https://capawesome.io/docs/sdks/capacitor/geofences/) and [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Background Geolocation plugin is typically used whenever an app needs to know where the device is over a period of time, for example:

- **Fitness and activity tracking**: Record runs, rides and hikes even when the screen is off.
- **Fleet and workforce management**: Track delivery drivers or field workers during their shift.
- **Navigation**: Keep the position up to date while the user switches to another app.
- **Safety**: Share the live location with family members or emergency contacts.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [Announcing the Capacitor Background Geolocation Plugin](https://capawesome.io/blog/announcing-the-capacitor-background-geolocation-plugin/): A tour of watch sessions, the native SQLite queue, and the HTTP upload pipeline.
- [Why iOS Stops Sending Background Location Updates](https://capawesome.io/blog/why-ios-stops-background-location-updates/): Core Location's background rules mapped to the iOS options of this plugin, from the `location` background mode to automatic pausing.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-background-geolocation` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-background-geolocation
npx cap sync
```

### Android

#### Permissions

The plugin already declares the location and foreground service permissions in its own manifest. If you want to receive position updates while the app is in the **background**, you must additionally declare the `ACCESS_BACKGROUND_LOCATION` permission in the `AndroidManifest.xml` file of your app before or after the `application` tag:

```
<!-- Required if you want to receive position updates while the app is in the background. -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

**Attention**: This permission is deliberately **not** declared by the plugin because Google Play requires a policy declaration and review for every app that requests background location access. Only declare it if your app really needs background tracking and make sure to complete the [location permissions declaration](https://support.google.com/googleplay/android-developer/answer/9799150) in the Google Play Console.

The `INTERNET` permission that the [HTTP Upload](#http-upload) feature requires is already declared by every Capacitor app template, so no additional configuration is needed for it.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$playServicesLocationVersion` version of `com.google.android.gms:play-services-location` (default: `21.4.0`)

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

### iOS

Add the `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription` keys to the `Info.plist` file of your app to explain why your app needs access to the location:

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>The app needs access to your location to track your position.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>The app needs access to your location to track your position, even while the app is in the background.</string>
```

If you want to receive position updates while the app is in the **background**, you must also enable the `location` background mode in the `Info.plist` file of your app:

```
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>
```

If you want to use the `requestTemporaryFullAccuracy(...)` method, you must also add the `NSLocationTemporaryUsageDescriptionDictionary` key to the `Info.plist` file of your app with one entry per purpose key:

```
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>navigation</key>
  <string>The app needs your precise location to provide turn-by-turn navigation.</string>
</dict>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get the current position, watch the position of the device, read queued positions, upload positions to a server, request temporary full accuracy, and check and request permissions.

### Get the current position

Get a one-shot position of the device with a configurable accuracy, timeout and maximum age. Only available on Android and iOS:

```
import { Accuracy, BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const getCurrentPosition = async () => {
  const { position } = await BackgroundGeolocation.getCurrentPosition({
    accuracy: Accuracy.High,
    timeout: 10000,
  });
  return position;
};
```

### Watch the position

Start a watch session to receive position updates via the `positionChange` event, even while the app is in the background. Errors that occur during an active watch session are delivered via the `positionError` event. Only one watch session can be active at a time. Only available on Android and iOS:

```
import { Accuracy, ActivityType, BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const startWatching = async () => {
  // Enable the queue so that no position is lost while the web view is suspended.
  await BackgroundGeolocation.setConfig({ maxSize: 50000 });
  await BackgroundGeolocation.addListener('positionChange', event => {
    console.log('New position: ', event.position);
  });
  await BackgroundGeolocation.addListener('positionError', event => {
    console.error('Position error: ', event.code, event.message);
  });
  await BackgroundGeolocation.startWatching({
    accuracy: Accuracy.High,
    distanceFilter: 10,
    androidInterval: 5000,
    androidNotification: {
      title: 'Location Tracking',
      text: 'Your location is being tracked.',
    },
    iosActivityType: ActivityType.Fitness,
  });
};

const stopWatching = async () => {
  await BackgroundGeolocation.stopWatching();
};

const isWatching = async () => {
  const { watching } = await BackgroundGeolocation.isWatching();
  return watching;
};
```

### Read queued positions

The plugin can store every position of a watch session in a local queue that survives app restarts, so your app can read the positions it missed while the web view was suspended. Enable the queue with `setConfig(...)` and drain it whenever your app is in the foreground again. Only available on Android and iOS:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const enableQueue = async () => {
  await BackgroundGeolocation.setConfig({ maxSize: 50000 });
};

const drainQueue = async () => {
  let hasMore = true;
  while (hasMore) {
    const result = await BackgroundGeolocation.getQueuedPositions({
      limit: 1000,
    });
    if (!result.positions.length) {
      break;
    }
    await persist(result.positions);
    await BackgroundGeolocation.deleteQueuedPositions({
      upToId: result.positions[result.positions.length - 1].id,
    });
    hasMore = result.hasMore;
  }
};
```

See [Queue](#queue) for all options, the drain loop and the queue behavior.

### Upload positions to a server

The plugin can upload every queued position to your own server without involving JavaScript, so that no position is lost while the device is offline. Provide the `url` option to enable it. Only available on Android and iOS:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const enableUpload = async () => {
  await BackgroundGeolocation.setConfig({
    url: 'https://api.example.com/positions',
    headers: {
      Authorization: 'Bearer eyJhbGciOi...',
    },
  });
};
```

See [HTTP Upload](#http-upload) for all options, the server contract and the response handling.

### Request temporary full accuracy

Ask users who have granted reduced location accuracy for full accuracy for the duration of the app session. The `NSLocationTemporaryUsageDescriptionDictionary` key must contain an entry for the given purpose key. Only available on iOS:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const requestTemporaryFullAccuracy = async () => {
  await BackgroundGeolocation.requestTemporaryFullAccuracy({
    purposeKey: 'navigation',
  });
};
```

### Check and request permissions

Check and request the permissions to access the location services. The background location permission must be requested in **two steps** on both platforms. Only available on Android and iOS:

1. Request the `location` (and optionally `notifications`) permission first. This displays the default system dialog.
1. Request the `backgroundLocation` permission in a **separate** call, ideally after explaining to the user why the app needs it:
1. On **Android 11+**, the user is taken to the location settings of the app where the `Allow all the time` option must be selected. Google recommends showing an in-app explanation before triggering this step.
1. On **iOS**, the operating system presents the upgrade prompt that asks the user to change the permission from `While Using the App` to `Always`.

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const checkPermissions = async () => {
  return BackgroundGeolocation.checkPermissions();
};

const requestPermissions = async () => {
  return BackgroundGeolocation.requestPermissions({
    permissions: ['location', 'notifications'],
  });
};

const requestBackgroundLocationPermission = async () => {
  return BackgroundGeolocation.requestPermissions({
    permissions: ['backgroundLocation'],
  });
};
```

If a permission was permanently denied, you can take the user to the app settings to change it:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const openSettings = async () => {
  await BackgroundGeolocation.openSettings();
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`clearQueue()`](#clearqueue)
- [`deleteQueuedPositions(...)`](#deletequeuedpositions)
- [`getConfig()`](#getconfig)
- [`getCurrentPosition(...)`](#getcurrentposition)
- [`getQueuedPositions(...)`](#getqueuedpositions)
- [`getQueueStatus()`](#getqueuestatus)
- [`isWatching()`](#iswatching)
- [`openSettings()`](#opensettings)
- [`requestPermissions(...)`](#requestpermissions)
- [`requestTemporaryFullAccuracy(...)`](#requesttemporaryfullaccuracy)
- [`resetConfig()`](#resetconfig)
- [`setConfig(...)`](#setconfig)
- [`startWatching(...)`](#startwatching)
- [`stopWatching()`](#stopwatching)
- [`triggerUpload()`](#triggerupload)
- [`addListener('positionChange', ...)`](#addlistenerpositionchange-)
- [`addListener('positionError', ...)`](#addlistenerpositionerror-)
- [`addListener('uploadFailed', ...)`](#addlisteneruploadfailed-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the current permission status.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### clearQueue()

```
clearQueue() => Promise<void>
```

Delete all positions from the queue and reset the dropped counter.

This method can be called with or without an active watch session, for example to discard pending positions when the user signs out.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### deleteQueuedPositions(...)

```
deleteQueuedPositions(options: DeleteQueuedPositionsOptions) => Promise<void>
```

Delete all queued positions up to and including the given id.

Call this method after the positions returned by `getQueuedPositions()` have been persisted by your app.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `DeleteQueuedPositionsOptions` |

**Since:** 0.2.0

______________________________________________________________________

### getConfig()

```
getConfig() => Promise<GetConfigResult>
```

Get the configuration that was last set via `setConfig(...)`.

Only the properties that were provided are returned, so the result can be spread into `setConfig(...)` to change a single property:

```
const config = await BackgroundGeolocation.getConfig();
await BackgroundGeolocation.setConfig({ ...config, maxSize: 5000 });
```

An empty object is returned if `setConfig(...)` has not been called yet.

Only available on Android and iOS.

**Returns:** `Promise<SetConfigOptions>`

**Since:** 0.2.0

______________________________________________________________________

### getCurrentPosition(...)

```
getCurrentPosition(options?: GetCurrentPositionOptions | undefined) => Promise<GetCurrentPositionResult>
```

Get the current position of the device.

On **Android**, the location permission is requested automatically if it has not been granted yet.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `GetCurrentPositionOptions` |

**Returns:** `Promise<GetCurrentPositionResult>`

**Since:** 0.0.1

______________________________________________________________________

### getQueuedPositions(...)

```
getQueuedPositions(options?: GetQueuedPositionsOptions | undefined) => Promise<GetQueuedPositionsResult>
```

Get the positions that are currently stored in the queue, oldest first.

The positions are **not** deleted from the queue. Call `deleteQueuedPositions(...)` after the positions have been persisted by your app.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `GetQueuedPositionsOptions` |

**Returns:** `Promise<GetQueuedPositionsResult>`

**Since:** 0.2.0

______________________________________________________________________

### getQueueStatus()

```
getQueueStatus() => Promise<GetQueueStatusResult>
```

Get the current status of the queue.

This method can be called with or without an active watch session.

Only available on Android and iOS.

**Returns:** `Promise<GetQueueStatusResult>`

**Since:** 0.2.0

______________________________________________________________________

### isWatching()

```
isWatching() => Promise<IsWatchingResult>
```

Check whether or not a watch session is currently active.

Only available on Android and iOS.

**Returns:** `Promise<IsWatchingResult>`

**Since:** 0.0.1

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the native app settings page to allow the user to grant the app the required permissions.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions.

The `backgroundLocation` permission must be requested in a **second**, separate call after the `location` permission has been granted:

- On **Android 11+**, the user is taken to the location settings of the app where the `Allow all the time` option must be selected.
- On **iOS**, the operating system presents the upgrade prompt that asks the user to change the permission from `While Using the App` to `Always`.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### requestTemporaryFullAccuracy(...)

```
requestTemporaryFullAccuracy(options: RequestTemporaryFullAccuracyOptions) => Promise<void>
```

Request temporary access to the full accuracy location of the device.

Call this method if the user has granted the app reduced location accuracy to ask for full accuracy for the duration of the app session.

The `NSLocationTemporaryUsageDescriptionDictionary` key must be defined in the `Info.plist` file of your app with an entry for the given `purposeKey`.

Only available on iOS.

| Param         | Type                                  |
| ------------- | ------------------------------------- |
| **`options`** | `RequestTemporaryFullAccuracyOptions` |

**Since:** 0.0.1

______________________________________________________________________

### resetConfig()

```
resetConfig() => Promise<void>
```

Discard the configuration so that no positions are stored or uploaded.

Positions that are already queued are kept, use `clearQueue()` to discard them.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### setConfig(...)

```
setConfig(options: SetConfigOptions) => Promise<void>
```

Set the configuration of the position queue and of the upload.

The configuration is persisted natively so that it keeps working when the operating system wakes your app without a web view.

Positions are stored in the queue if `maxSize` or `url` is provided, and they are uploaded if `url` is provided. Use `resetConfig()` to stop storing and uploading positions.

**This method replaces the whole configuration**, so every property you omit falls back to its default. `setConfig({ maxSize: 5000 })` therefore also stops the upload, because `url` is no longer set. Keep your configuration in one place and pass it whole:

```
await BackgroundGeolocation.setConfig({ maxSize: 5000, url });
```

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetConfigOptions` |

**Since:** 0.2.0

______________________________________________________________________

### startWatching(...)

```
startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
```

Start watching the position of the device.

Position updates are delivered via the `positionChange` event. Errors that occur after the watch session has been started (e.g. the user disables the location services) are delivered via the `positionError` event.

Only one watch session can be active at a time. The promise rejects with the `ALREADY_WATCHING` error code if a watch session is already active.

On **Android**, a foreground service with a persistent notification is started so that the app keeps receiving position updates while it is in the background. For this reason, the `androidNotification` option must be provided. The location permission is requested automatically if it has not been granted yet.

On **iOS**, position updates are delivered while the app is in the background if the `location` background mode is enabled in the app.

If the queue is enabled via `setConfig(...)`, every position of the watch session is additionally stored in the local queue.

Without the `backgroundLocation` permission, the watch session keeps working but position updates may be suspended while the app is in the background.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartWatchingOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopWatching()

```
stopWatching() => Promise<void>
```

Stop the active watch session.

On **Android**, this also stops the foreground service and removes the associated notification.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### triggerUpload()

```
triggerUpload() => Promise<void>
```

Immediately attempt to upload all queued positions.

Any pending retry backoff is cancelled and a new upload attempt is started right away. The promise resolves as soon as the attempt has been scheduled, not when the positions have been delivered.

The promise rejects if no `url` has been set via `setConfig(...)`.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### addListener('positionChange', ...)

```
addListener(eventName: 'positionChange', listenerFunc: (event: PositionChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new position is available during an active watch session.

This event is only delivered while the web view is alive. If the queue is enabled, treat the queue as the single source of truth instead.

Only available on Android and iOS.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'positionChange'`                     |
| **`listenerFunc`** | `(event: PositionChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('positionError', ...)

```
addListener(eventName: 'positionError', listenerFunc: (event: PositionErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during an active watch session, for example when the user disables the location services or revokes the location permission.

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'positionError'`                     |
| **`listenerFunc`** | `(event: PositionErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('uploadFailed', ...)

```
addListener(eventName: 'uploadFailed', listenerFunc: (event: UploadFailedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an upload attempt of queued positions fails.

The affected positions remain in the queue and are retried automatically unless the server rejected them permanently.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'uploadFailed'`                     |
| **`listenerFunc`** | `(event: UploadFailedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop                     | Type              | Description                                                                                                                                                                                                                   | Since |
| ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`backgroundLocation`** | `PermissionState` | Permission state for using the location services while the app is in the background. On **Android 9 and older**, this always mirrors the `location` permission state since no separate background location permission exists. | 0.0.1 |
| **`location`**           | `PermissionState` | Permission state for using the location services while the app is in use.                                                                                                                                                     | 0.0.1 |
| **`notifications`**      | `PermissionState` | Permission state for posting notifications. On **Android 12 and older** and on **iOS**, this is always `granted` since no notification permission is required.                                                                | 0.0.1 |

#### DeleteQueuedPositionsOptions

| Prop         | Type     | Description                                                                                           | Since |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------- | ----- |
| **`upToId`** | `number` | The id of the newest position to delete. All queued positions with this id or a lower id are deleted. | 0.2.0 |

#### SetConfigOptions

| Prop                | Type                         | Description                                                                                                                                                                                                                                                                                                                                                                                        | Default      | Since                                                                                                  |
| ------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| **`batchSize`**     | `number`                     | The maximum number of positions that are uploaded in a single request. Must be positive and must not be greater than `maxSize`. Set this option to `1` to upload each position immediately.                                                                                                                                                                                                        | `100`        | 0.2.0                                                                                                  |
| **`extras`**        | \`{ \[key: string\]: string  | number                                                                                                                                                                                                                                                                                                                                                                                             | boolean; }\` | Static metadata that is attached to every upload request as the `extras` property of the request body. |
| **`flushInterval`** | `number`                     | The maximum time in milliseconds before queued positions are uploaded, even if the batch size has not been reached yet. Must be positive.                                                                                                                                                                                                                                                          | `60000`      | 0.2.0                                                                                                  |
| **`headers`**       | `{ [key: string]: string; }` | Static HTTP headers that are sent with every upload request, for example for authorization.                                                                                                                                                                                                                                                                                                        |              | 0.2.0                                                                                                  |
| **`maxSize`**       | `number`                     | The maximum number of positions that are stored in the queue. When the queue is full, the oldest positions are dropped first. A stored position occupies about `210` bytes, so the default of `50000` needs about `10` MB. Must be positive. Set this option to `1` to keep only the most recent position, for example when you upload every position immediately and only the latest one matters. | `50000`      | 0.2.0                                                                                                  |
| **`url`**           | `string`                     | The URL the positions are uploaded to via HTTP `POST`. Providing this property enables the upload. Omit it to keep the positions on the device only.                                                                                                                                                                                                                                               |              | 0.2.0                                                                                                  |

#### GetCurrentPositionResult

| Prop           | Type       | Description                         | Since |
| -------------- | ---------- | ----------------------------------- | ----- |
| **`position`** | `Position` | The current position of the device. | 0.0.1 |

#### Position

| Prop                   | Type      | Description                                                                         | Since                                                                                                                                                                  |
| ---------------------- | --------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`accuracy`**         | `number`  | The estimated horizontal accuracy radius of the position in meters.                 | 0.0.1                                                                                                                                                                  |
| **`altitude`**         | \`number  | null\`                                                                              | The altitude of the position in meters or `null` if the altitude is not available.                                                                                     |
| **`altitudeAccuracy`** | \`number  | null\`                                                                              | The estimated accuracy of the altitude in meters or `null` if the altitude accuracy is not available.                                                                  |
| **`bearing`**          | \`number  | null\`                                                                              | The direction in which the device is traveling in degrees relative to north or `null` if the bearing is not available.                                                 |
| **`latitude`**         | `number`  | The latitude of the position in degrees.                                            | 0.0.1                                                                                                                                                                  |
| **`longitude`**        | `number`  | The longitude of the position in degrees.                                           | 0.0.1                                                                                                                                                                  |
| **`simulated`**        | \`boolean | null\`                                                                              | Whether or not the position was delivered by a mock location provider. On **iOS**, this is always `null` since the operating system does not provide this information. |
| **`speed`**            | \`number  | null\`                                                                              | The speed of the device in meters per second or `null` if the speed is not available.                                                                                  |
| **`timestamp`**        | `number`  | The time at which the position was determined in milliseconds since the Unix epoch. | 0.0.1                                                                                                                                                                  |

#### GetCurrentPositionOptions

| Prop                              | Type       | Description                                                                                                                                                                                                                                                                   | Default         | Since |
| --------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----- |
| **`accuracy`**                    | `Accuracy` | The desired accuracy of the position.                                                                                                                                                                                                                                         | `Accuracy.High` | 0.0.1 |
| **`androidForceLocationManager`** | `boolean`  | Whether or not to force the use of the platform location manager instead of the fused location provider, even if Google Play services is available. See the option of the same name of `startWatching(...)` for the cases in which this is useful. Only available on Android. | `false`         | 0.2.0 |
| **`maximumAge`**                  | `number`   | The maximum age in milliseconds of a cached position that is accepted as the current position. If set to `0`, a fresh position is always fetched.                                                                                                                             | `0`             | 0.0.1 |
| **`timeout`**                     | `number`   | The maximum time in milliseconds to wait for a position. The promise rejects with the `TIMEOUT` error code if no position is available within this time.                                                                                                                      | `10000`         | 0.0.1 |

#### GetQueuedPositionsResult

| Prop            | Type               | Description                                                     | Since |
| --------------- | ------------------ | --------------------------------------------------------------- | ----- |
| **`hasMore`**   | `boolean`          | Whether or not more positions are available than were returned. | 0.2.0 |
| **`positions`** | `QueuedPosition[]` | The queued positions, oldest first.                             | 0.2.0 |

#### QueuedPosition

| Prop     | Type     | Description                                                                                         | Since |
| -------- | -------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`id`** | `number` | The id of the position in the queue. The id is unique per app installation and strictly increasing. | 0.2.0 |

#### GetQueuedPositionsOptions

| Prop          | Type     | Description                                                                                                                                                              | Default | Since |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`afterId`** | `number` | The id of the newest position that has already been read. Only positions with a higher id are returned. If not provided, the oldest positions in the queue are returned. |         | 0.2.0 |
| **`limit`**   | `number` | The maximum number of positions to return.                                                                                                                               | `100`   | 0.2.0 |

#### GetQueueStatusResult

| Prop                 | Type     | Description                                                                                                                                                     | Since                                                                                                                                                                  |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`droppedCount`**   | `number` | The number of positions that were dropped without being read since the queue was last cleared, for example because the queue was full or the positions expired. | 0.2.0                                                                                                                                                                  |
| **`lastUploadedAt`** | \`number | null\`                                                                                                                                                          | The time at which the last batch of positions was uploaded successfully in milliseconds since the Unix epoch or `null` if no batch has been uploaded successfully yet. |
| **`pendingCount`**   | `number` | The number of positions that are currently stored in the queue.                                                                                                 | 0.2.0                                                                                                                                                                  |

#### IsWatchingResult

| Prop           | Type      | Description                                         | Since |
| -------------- | --------- | --------------------------------------------------- | ----- |
| **`watching`** | `boolean` | Whether or not a watch session is currently active. | 0.0.1 |

#### RequestPermissionsOptions

| Prop              | Type               | Description                 | Default                         | Since |
| ----------------- | ------------------ | --------------------------- | ------------------------------- | ----- |
| **`permissions`** | `PermissionType[]` | The permissions to request. | `['location', 'notifications']` | 0.0.1 |

#### RequestTemporaryFullAccuracyOptions

| Prop             | Type     | Description                                                                                                                                                                              | Since |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`purposeKey`** | `string` | The key of the entry in the `NSLocationTemporaryUsageDescriptionDictionary` dictionary of the `Info.plist` file of your app that describes why the app needs the full accuracy location. | 0.0.1 |

#### StartWatchingOptions

| Prop                              | Type                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Default              | Since |
| --------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----- |
| **`accuracy`**                    | `Accuracy`                   | The desired accuracy of the position updates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `Accuracy.High`      | 0.0.1 |
| **`androidForceLocationManager`** | `boolean`                    | Whether or not to force the use of the platform location manager instead of the fused location provider, even if Google Play services is available. Devices without Google Play services use the platform location manager anyway, so this option is not needed for them. Set it to `true` to receive the unmodified positions of a single provider instead of the fused ones, or if the fused location provider is unreliable on a device that reports Google Play services as available. This consumes more battery. Only available on Android. | `false`              | 0.0.1 |
| **`androidInterval`**             | `number`                     | The interval in milliseconds at which position updates are requested. A position is requested on every interval, whether or not the device has moved, so use `distanceFilter` to skip the positions of a device that stands still. iOS has no equivalent option: the operating system decides how often it reports a position, which is far less often while the device is stationary. Only available on Android.                                                                                                                                 | `5000`               | 0.0.1 |
| **`androidNotification`**         | `AndroidNotificationOptions` | The configuration of the notification that is displayed while the watch session is active. This option must be provided on Android. Only available on Android.                                                                                                                                                                                                                                                                                                                                                                                    |                      | 0.0.1 |
| **`distanceFilter`**              | `number`                     | The minimum distance in meters that the device must move before a new position update is delivered. Set this option to `0` to receive every position, which also means that a device that stands still keeps reporting the same position.                                                                                                                                                                                                                                                                                                         | `10`                 | 0.0.1 |
| **`iosActivityType`**             | `ActivityType`               | The type of activity for which the position updates are used. This helps the operating system to decide when position updates may be paused automatically. Only available on iOS.                                                                                                                                                                                                                                                                                                                                                                 | `ActivityType.Other` | 0.0.1 |
| **`iosPausesAutomatically`**      | `boolean`                    | Whether or not the operating system is allowed to pause position updates automatically when the device is unlikely to move (e.g. when the user is stationary for a longer period of time). This can significantly improve battery life. Only available on iOS.                                                                                                                                                                                                                                                                                    | `false`              | 0.0.1 |
| **`iosShowBackgroundIndicator`**  | `boolean`                    | Whether or not the status bar indicator is displayed when the app uses the location services in the background. Only available on iOS.                                                                                                                                                                                                                                                                                                                                                                                                            | `true`               | 0.0.1 |

#### AndroidNotificationOptions

| Prop              | Type     | Description                                                                                                                                                                 | Default                    | Since |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----- |
| **`channelName`** | `string` | The name of the notification channel in which the notification is displayed.                                                                                                | `'Background Geolocation'` | 0.0.1 |
| **`color`**       | `string` | The color of the notification as a hex color code (e.g. `#42A5F5`).                                                                                                         |                            | 0.0.1 |
| **`icon`**        | `string` | The name of the drawable resource that is displayed as the small icon of the notification (e.g. `ic_stat_location`). If not provided, the launcher icon of the app is used. |                            | 0.0.1 |
| **`text`**        | `string` | The body text of the notification.                                                                                                                                          |                            | 0.0.1 |
| **`title`**       | `string` | The title of the notification.                                                                                                                                              |                            | 0.0.1 |

#### PluginListenerHandle

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

#### PositionChangeEvent

| Prop           | Type       | Description                     | Since |
| -------------- | ---------- | ------------------------------- | ----- |
| **`position`** | `Position` | The new position of the device. | 0.0.1 |

#### PositionErrorEvent

| Prop          | Type        | Description        | Since |
| ------------- | ----------- | ------------------ | ----- |
| **`code`**    | `ErrorCode` | The error code.    | 0.0.1 |
| **`message`** | `string`    | The error message. | 0.0.1 |

#### UploadFailedEvent

| Prop             | Type     | Description                                                       | Since |
| ---------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`message`**    | `string` | The error message.                                                | 0.0.1 |
| **`statusCode`** | `number` | The HTTP status code of the response, if a response was received. | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### GetConfigResult

`SetConfigOptions`

#### PermissionType

The permissions that can be requested.

`'backgroundLocation' | 'location' | 'notifications'`

### Enums

#### Accuracy

| Members        | Value        | Description                                                                                                                         | Since |
| -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Balanced`** | `'BALANCED'` | A balance between accuracy and power consumption. The position is accurate to within about a hundred meters.                        | 0.0.1 |
| **`High`**     | `'HIGH'`     | The most accurate position that is available. This uses the most power and should only be used when a precise position is required. | 0.0.1 |
| **`Low`**      | `'LOW'`      | A low accuracy position with minimal power consumption. The position is accurate to within about a kilometer.                       | 0.0.1 |

#### ActivityType

| Members                    | Value                     | Description                                                                                    | Since |
| -------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | ----- |
| **`Airborne`**             | `'AIRBORNE'`              | [Position](#position) updates for activities in the air (e.g. flying).                         | 0.0.1 |
| **`AutomotiveNavigation`** | `'AUTOMOTIVE_NAVIGATION'` | [Position](#position) updates for automotive navigation.                                       | 0.0.1 |
| **`Fitness`**              | `'FITNESS'`               | [Position](#position) updates for fitness activities (e.g. walking, running or cycling).       | 0.0.1 |
| **`Other`**                | `'OTHER'`                 | [Position](#position) updates for activities that are not covered by the other activity types. | 0.0.1 |
| **`OtherNavigation`**      | `'OTHER_NAVIGATION'`      | [Position](#position) updates for vehicular navigation that is not automotive (e.g. boating).  | 0.0.1 |

#### ErrorCode

| Members                        | Value                          | Description                                         | Since |
| ------------------------------ | ------------------------------ | --------------------------------------------------- | ----- |
| **`AlreadyWatching`**          | `'ALREADY_WATCHING'`           | A watch session is already active.                  | 0.0.1 |
| **`LocationServicesDisabled`** | `'LOCATION_SERVICES_DISABLED'` | The location services are disabled on the device.   | 0.0.1 |
| **`PermissionDenied`**         | `'PERMISSION_DENIED'`          | The location permission has not been granted.       | 0.0.1 |
| **`PositionUnavailable`**      | `'POSITION_UNAVAILABLE'`       | The position is currently not available.            | 0.0.1 |
| **`Timeout`**                  | `'TIMEOUT'`                    | No position was available within the given timeout. | 0.0.1 |

## Queue

The plugin can store every position of a watch session in a local SQLite queue. The queue is the durable record of a watch session: it is written natively, survives app restarts and does not depend on a running web view. The [`positionChange`](#addlistenerpositionchange-) event is only an ephemeral live feed on top of it.

### Enabling the queue

The queue is **opt-in** because precise location history at rest is sensitive data. Enable it with `setConfig(...)`:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const enableQueue = async () => {
  await BackgroundGeolocation.setConfig({
    maxSize: 50000,
  });
};
```

The configuration is persisted natively so that the plugin keeps working when the operating system runs your app without a web view. Call `setConfig(...)` on every app start anyway: the stored copy is only a cache of your last call, and it is discarded whenever the plugin's configuration format changes in a future version. Queued positions are never discarded with it.

**Attention**: The configuration you pass replaces the stored one entirely. Every property you omit falls back to its default, so read the stored configuration with `getConfig()` first if you only want to change a single property:

```
const config = await BackgroundGeolocation.getConfig();
await BackgroundGeolocation.setConfig({ ...config, maxSize: 10000 });
```

Call `resetConfig()` to discard the configuration again. Positions that are already queued are kept, use `clearQueue()` to discard them:

```
await BackgroundGeolocation.resetConfig();
```

### Queue Options

| Option    | Default | Description                                                                                                 |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `maxSize` | `50000` | The maximum number of queued positions. When the queue is full, the **oldest** positions are dropped first. |

The default `maxSize` of `50000` records is about 10 MB on disk and about 100 hours of walking at the default `distanceFilter` of `10` meters, at which a device that stands still records nothing. It is a disaster ceiling, not a working set: an app that drains the queue whenever it is in the foreground sits close to zero.

### Draining the queue

Reading and deleting are two separate operations, because the watch session keeps recording between them. Read a page of positions, persist them in your app, then delete everything up to the id of the last position you persisted:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const drainQueue = async () => {
  let hasMore = true;
  while (hasMore) {
    const result = await BackgroundGeolocation.getQueuedPositions({
      limit: 1000,
    });
    if (!result.positions.length) {
      break;
    }
    await persist(result.positions);
    await BackgroundGeolocation.deleteQueuedPositions({
      upToId: result.positions[result.positions.length - 1].id,
    });
    hasMore = result.hasMore;
  }
};
```

Every queued position is a [`Position`](#position) object with an additional `id` property. Ids are unique per app installation and strictly increasing, so `deleteQueuedPositions(...)` can never delete a position that is newer than the one you read. The `limit` option defaults to `100`, so a completely full queue is about 50 calls at `limit: 1000`.

Use `getQueueStatus()` to inspect the queue and `clearQueue()` to discard everything, for example when the user signs out:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const getQueueStatus = async () => {
  const { pendingCount, droppedCount, lastUploadedAt } = await BackgroundGeolocation.getQueueStatus();
  console.log(`${pendingCount} positions pending, ${droppedCount} dropped, last upload: ${lastUploadedAt}`);
};

const clearQueue = async () => {
  await BackgroundGeolocation.clearQueue();
};
```

### Queue Behavior

- **Persistence**: The queue is stored in a local SQLite database and survives app restarts and force-quits. Positions are only deleted when your app deletes them, the server acknowledged them or they were evicted.
- **Capacity**: The queue holds at most `maxSize` positions. If the queue is full, the **oldest** positions are dropped first.
- **Observability**: The `droppedCount` property of `getQueueStatus()` counts the positions that were dropped since the queue was last cleared. It is persisted and only reset by `clearQueue()`.
- **Ordering**: Positions are returned oldest first and their ids are strictly increasing.
- **Encryption at rest**: The queue database is not encrypted. It is stored in the sandboxed app storage of the operating system.

### Caveats

- **Positions arrive twice**: While the web view is alive, every position is delivered via the `positionChange` event **and** stored in the queue. With the queue enabled, treat the queue as the single source of truth and use the event for live UI only, otherwise you process every position twice.
- **The queue only fills while the watch session is alive**: If the user force-quits the app, the watch session ends and no further positions are recorded until it is started again. The already queued positions are not lost, but the gap in between cannot be filled.

## HTTP Upload

The plugin can upload every queued position to your own server without involving JavaScript. Positions are uploaded in batches and only deleted from the [queue](#queue) after the server has acknowledged them. Since the whole pipeline runs natively, it keeps working while the web view is suspended.

**Attention**: The upload drains the same queue that `getQueuedPositions(...)` reads. Positions are stored once and deleted once, so a position your app deletes with `deleteQueuedPositions(...)` is never uploaded, and a position the server acknowledged is no longer readable. Use either the upload or your own drain loop, not both.

### Options

Provide the `url` option to enable the upload pipeline. It is persisted, so it stays active across app restarts until it is changed or discarded. Failed upload attempts are reported via the `uploadFailed` event:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const enableUpload = async () => {
  await BackgroundGeolocation.addListener('uploadFailed', event => {
    console.error('Upload failed: ', event.statusCode, event.message);
  });
  await BackgroundGeolocation.setConfig({
    url: 'https://api.example.com/positions',
    batchSize: 100,
    flushInterval: 60000,
    headers: {
      Authorization: 'Bearer eyJhbGciOi...',
    },
    extras: {
      userId: 'abc',
    },
  });
};
```

Providing `url` also enables the queue, because the upload drains it. A rotated authorization header can be applied without stopping the watch session by calling `setConfig(...)` again with the updated configuration.

Call `resetConfig()` to discard the configuration again. Queued positions are kept and are uploaded as soon as the upload is enabled again:

```
await BackgroundGeolocation.resetConfig();
```

To stop the upload but keep storing positions, call `setConfig(...)` again without `url`:

```
const { url, ...config } = await BackgroundGeolocation.getConfig();
await BackgroundGeolocation.setConfig(config);
```

An upload attempt can be triggered manually at any time:

```
import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

const triggerUpload = async () => {
  await BackgroundGeolocation.triggerUpload();
};
```

### Server Contract

Positions are uploaded with an HTTP `POST` request and the `Content-Type: application/json; charset=utf-8` header. Your own `headers` are applied afterwards and may override it. The request body looks as follows:

```
{
  "positions": [
    {
      "id": 4711,
      "latitude": 52.52,
      "longitude": 13.405,
      "accuracy": 5,
      "altitude": null,
      "altitudeAccuracy": null,
      "bearing": null,
      "speed": null,
      "simulated": false,
      "timestamp": 1723291200000
    }
  ],
  "extras": { "userId": "abc" }
}
```

Every entry of the `positions` array is a [`Position`](#position) object with an additional `id` property. The `extras` property is omitted entirely if the `extras` option was not provided.

**Idempotency**: The `id` is unique per app installation and strictly increasing. Positions are delivered **at least once**, so the same position may be uploaded more than once, for example if the acknowledgment of the server is lost on the way back. Deduplicate the positions on the server by `id` per device to make the upload idempotent.

### Response Handling

The response body is always ignored. Only the status code decides what happens to the uploaded batch:

| Status Code                                        | Behavior                                                                                                                                           |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2xx`                                              | The batch is acknowledged and deleted from the queue. The next batch is uploaded immediately if more positions are pending.                        |
| `401`, `408`, `429`, `5xx`, network error, timeout | The batch stays at the head of the queue and is retried with an exponential backoff. A `uploadFailed` event is emitted.                            |
| Any other status code                              | The batch is **dropped permanently without being uploaded again** and a `uploadFailed` event is emitted. The upload continues with the next batch. |

**Attention**: A batch that the server rejects with any status code other than `2xx`, `401`, `408`, `429` or `5xx` (for example `400 Bad Request` or `422 Unprocessable Entity`) is deleted from the queue and **lost**. This is intentional: a permanently rejected batch must never block the head of the queue forever. `401` is treated as retryable, because it usually means an expired token rather than an unacceptable batch — refresh the credentials with `setConfig(...)` and the queued positions are uploaded afterwards. Make sure your endpoint answers with a retryable status code (e.g. `503`) if it is temporarily unable to accept positions, and listen to the `uploadFailed` event to detect such drops. Dropped positions are also counted in the `droppedCount` property of `getQueueStatus()`.

The request timeout is 30 seconds. Retries start with a delay of 5 seconds and double after every attempt up to a maximum of 10 minutes. The backoff is reset after every successful upload, whenever `setConfig(...)` is called with a `url` and whenever `triggerUpload()` is called.

### Upload Behavior

- **Delivery window**: Positions are uploaded whenever the app process is alive and a `url` is configured, with or without an active watch session. Enabling the upload first deletes expired positions and then immediately uploads everything that is left over from previous sessions.
- **Acknowledgment**: Positions are only deleted from the queue after the server acknowledged them or rejected them permanently.
- **Shared queue**: The uploader and `getQueuedPositions(...)` drain the same queue. If your app reads and deletes positions itself, the uploader only sees what is left.
- **Without a `url`**: The queue is left untouched. It is neither uploaded nor cleared.
- **Observability**: Permanently rejected batches are counted in the `droppedCount` property of `getQueueStatus()` and `lastUploadedAt` reports the time of the last successful upload. Both values are persisted.

### Instant Upload

There is no dedicated mode for uploading each position on its own. Set the `batchSize` option to `1` instead to upload every position as soon as it arrives:

```
await BackgroundGeolocation.setConfig({
  url: 'https://api.example.com/positions',
  batchSize: 1,
});
```

### Battery Consumption

Every upload wakes up the cellular radio, which is one of the most expensive operations on a mobile device. Uploading one position at a time (see [Instant Upload](#instant-upload)) therefore has a noticeable impact on the battery life. Prefer a larger `batchSize` and a longer `flushInterval` whenever your use case allows it, so that many positions share a single radio wake-up.

### Testing

The free [Background Geolocation Playground](https://background-geolocation-playground.capawesome.io) webpage is a ready-to-use upload target, so you can verify the upload pipeline before your own endpoint exists. Generate a session key on the webpage, use it as bearer token and every uploaded position appears in a table and on a map:

```
await BackgroundGeolocation.setConfig({
  url: 'https://background-geolocation-playground.capawesome.io/v1/positions',
  headers: {
    Authorization: 'Bearer <YOUR_SESSION_KEY>',
  },
});
```

**Attention**: Session keys and recorded positions are deleted after 14 days and everyone who knows the session key can view its positions, so use the webpage for debugging and testing only and never in production.

### Deliberately Not Supported

The following features are intentionally not part of the upload pipeline:

- **Network constraints**: Uploads cannot be restricted to Wi-Fi or unmetered networks.
- **Response processing**: The response body of the server is always ignored, so the server cannot send commands back to the device.
- **Upload after a force-quit**: Queued positions are not uploaded while the app is terminated. They are uploaded the next time the app is started.

## FAQ

### How is this plugin different from other similar plugins?

It is built for reliable background location tracking with a correctly plumbed Android 14+ foreground service, a first-class permissions API that handles the two-step background upgrade flow, and real tuning knobs for accuracy, distance filtering and update interval. It also reports mock locations on Android, supports temporary full-accuracy requests on iOS, and falls back to the platform location manager on devices without Google Play services — all through one fully typed, actively maintained API with dedicated support. If you only need a single foreground position, a simpler geolocation setup may suffice; if you need dependable tracking that keeps running in the background, this plugin is made for it.

### Does the tracking continue when the user force-quits the app?

No. On both platforms, the watch session ends when the user force-quits (terminates) the app. This is an operating system restriction. Only operating-system-managed APIs like geofencing can relaunch a terminated app. Take a look at the [Geofences](https://capawesome.io/docs/sdks/capacitor/geofences/) plugin if you need this capability.

### Why is the `androidNotification` option required?

On Android, receiving position updates while the app is in the background requires a foreground service, and every foreground service must display a persistent notification. The plugin builds this notification from the `androidNotification` option so that you have full control over its content.

### Does the plugin work on devices without Google Play services?

Yes. The plugin automatically falls back to the platform location manager if Google Play services is not available on the device (e.g. on certain Huawei devices). You can also force this behavior with the `androidForceLocationManager` option.

### Why does the plugin not declare the `ACCESS_BACKGROUND_LOCATION` permission?

Google Play requires a policy declaration and review for every app that requests background location access. If the plugin declared this permission, every app using the plugin would be subject to this review, even if it only needs foreground location access. Therefore, the permission must be declared at the app level (see [Installation](#installation)).

### Can I start multiple watch sessions at the same time?

No. Only one watch session can be active at a time. The native location engine delivers one stream of position updates, so multiple concurrent watchers would only be an illusion with a shared configuration. Call `stopWatching()` before starting a new watch session with different options.

### How can I reduce the battery consumption?

The plugin deliberately does not include a motion-detection state machine that turns the GPS on and off based on accelerometer data. Instead, it exposes real tuning knobs: use a lower `accuracy` (e.g. `Accuracy.Balanced` instead of `Accuracy.High`), increase the `distanceFilter` to reduce the number of position updates and increase the `androidInterval` option on Android.

On iOS, you can additionally enable the `iosPausesAutomatically` option so that the operating system pauses the position updates when the device is unlikely to move. Be aware of the trade-off: the operating system decides on its own when to pause and only resumes the position updates once the device has moved significantly again, so a watch session can stay silent for a long time. The plugin logs both the pause and the resume, but keeps the watch session active, which means that `isWatching()` still returns `true` while the position updates are paused. [Why iOS Stops Sending Background Location Updates](https://capawesome.io/blog/why-ios-stops-background-location-updates/) covers this and the other Core Location rules that stop background updates on iOS.

### What happens if the user grants only approximate location?

On Android, the user can grant approximate instead of precise location. This is not reported separately but is reflected in the `accuracy` property of each position. On iOS, the user can grant reduced accuracy, which you can upgrade for the duration of the app session using `requestTemporaryFullAccuracy(...)`.

### Why are queued positions not uploaded after force-quit?

Uploading requires a running app process. When the user force-quits (terminates) the app, no more requests can be sent. The queued positions are **not** lost though: they stay in the local queue and are uploaded as soon as the app is started again. See [Queue Behavior](#queue-behavior) for details.

### How do I secure the upload endpoint?

Use the `headers` option to send a static credential (e.g. `Authorization: Bearer ...`) with every upload request and always use an `https://` URL, since the credential is otherwise sent in plain text. On iOS, App Transport Security blocks plain `http://` requests by default anyway. Call `setConfig(...)` again with the full configuration whenever the token is rotated, which applies the new header without interrupting the watch session.

### How can I test the upload endpoint locally?

Point the `url` option to a local HTTP endpoint that logs the request body. A few lines of Node.js are enough:

```
// server.js
import { createServer } from 'node:http';

createServer((request, response) => {
  let body = '';
  request.on('data', chunk => (body += chunk));
  request.on('end', () => {
    console.log(JSON.parse(body));
    response.writeHead(200).end();
  });
}).listen(3000);
```

Start it with `node server.js` and use the IP address of your development machine in the `url` option (e.g. `http://192.168.1.10:3000`). On the Android emulator, use `http://10.0.2.2:3000` instead. Plain `http://` requires an App Transport Security exception on iOS and a network security configuration that allows cleartext traffic on Android, so it is often easier to expose the local server via an HTTPS tunnel. Answer with a `503` status code to observe the retry behavior and with a `400` status code to observe a permanently dropped batch.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/): Convert the tracked positions into human-readable addresses.
- [Geofences](https://capawesome.io/docs/sdks/capacitor/geofences/): Monitor circular regions with operating-system-managed geofencing, including delivery when the app is terminated.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Take the user to the app settings, for example to grant the background location permission.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-geolocation/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-geolocation/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-geolocation/LICENSE).

# Capacitor Background Task Plugin

Capacitor plugin for running background tasks.

## Use Cases

The Background Task plugin is typically used to finish short-running work when the app moves to the background, for example:

- **Finish network requests**: Complete an upload or API request that was started while the app was in the foreground.
- **Save application state**: Persist unsaved user input or app state before the OS puts the app to sleep.
- **Sync data**: Finish writing pending changes to your backend or local storage.
- **Clean up resources**: Close connections or release resources gracefully before the app is suspended.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-background-task` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-background-task
npx cap sync
```

## Configuration

No configuration required for this plugin.

## Usage

```
import { App } from '@capacitor/app';
import { BackgroundTask } from '@capawesome/capacitor-background-task';

App.addListener('appStateChange', async ({ isActive }) => {
  if (isActive) {
    return;
  }
  // The app state has been changed to inactive.
  // Start the background task by calling `beforeExit`.
  const taskId = await BackgroundTask.beforeExit(async () => {
    // Run your code...
    // Finish the background task as soon as everything is done.
    BackgroundTask.finish({ taskId });
  });
});
```

## API

- [`beforeExit(...)`](#beforeexit)
- [`finish(...)`](#finish)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### beforeExit(...)

```
beforeExit(cb: () => void) => Promise<CallbackID>
```

Call this method when the app moves to the background. It allows the app to continue running a task in the background.

On **iOS** this method should be finished in less than 30 seconds.

Only available on Android and iOS.

| Param    | Type         |
| -------- | ------------ |
| **`cb`** | `() => void` |

**Returns:** `Promise<string>`

______________________________________________________________________

### finish(...)

```
finish(options: FinishOptions) => void
```

Finish the current background task. The OS will put the app to sleep.

Only available on Android and iOS.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `FinishOptions` |

______________________________________________________________________

### Interfaces

#### FinishOptions

| Prop         | Type         |
| ------------ | ------------ |
| **`taskId`** | `CallbackID` |

### Type Aliases

#### CallbackID

`string`

## Quirks

### iOS

On **iOS** the [UIKit framework](https://developer.apple.com/documentation/uikit) is used. Read more about the implementation and any limitations [here](https://developer.apple.com/documentation/uikit/app_and_environment/scenes/preparing_your_ui_to_run_in_the_background/extending_your_app_s_background_execution_time).

### Android

There is currently no ready implementation on **Android**. It's planned to add the support in the near future.

## FAQ

### How much time does my task have to run in the background?

On iOS, the task started with `beforeExit(...)` should be finished in less than 30 seconds. As soon as your work is done, call `finish(...)` so the OS can put the app to sleep. Read more about the underlying background execution mechanism in the [Apple documentation](https://developer.apple.com/documentation/uikit/app_and_environment/scenes/preparing_your_ui_to_run_in_the_background/extending_your_app_s_background_execution_time).

### Is this plugin supported on Android?

There is currently no ready implementation on Android, so the task is not extended there. Support for Android is planned for the future, see the [Quirks](#quirks) section.

### Can I run periodic or scheduled tasks with this plugin?

No, this plugin is designed to extend the execution time of your app when it moves to the background, so you can finish a short-running task. It does not schedule tasks that run while the app is closed.

### How do I know when the app moves to the background?

Use the `appStateChange` listener of the official `@capacitor/app` plugin, as shown in the [Usage](#usage) section. When `isActive` becomes `false`, call `beforeExit(...)` to start the background task.

### When do I have to call the `finish` method?

Call `finish(...)` with the task ID returned by `beforeExit(...)` as soon as everything is done. This tells the OS that the task is complete so it can put the app to sleep.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Alarm](https://capawesome.io/docs/sdks/capacitor/alarm/): Create system alarms and timers.
- [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Run a foreground service on Android for long-running work.
- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake while your app is in the foreground.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-task/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-task/LICENSE).

## Credits

This plugin is based on the [Capacitor Background Task](https://github.com/capawesome-team/capacitor-background-task) plugin. Thanks to everyone who contributed to the project!

# Capacitor Badge Plugin

Capacitor plugin to access and update the badge number of the app icon.

## Features

The Capacitor Badge plugin is one of the most complete app icon badge solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web (PWA).
- 🔢 **Badge management**: Get, set, increase, decrease, and clear badge counts.
- 💾 **Persistent badges**: Badge count persists after reboot or app restart.
- 🔄 **Auto-clear option**: Automatically reset counter when resuming the app.
- 🔐 **Permission handling**: Check and request badge display permissions.
- ⚙️ **Configurable**: Customize persistence and auto-clear behaviors.
- 🤝 **Compatibility**: Works alongside the [App Icon](https://capawesome.io/docs/sdks/capacitor/app-icon/) and [Firebase Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Badge plugin is typically used to show a count on the app icon that reflects pending items, for example:

- **Unread messages**: Show the number of unread chat messages or emails on the app icon.
- **Pending notifications**: Keep the badge in sync with the notifications the user has not yet seen.
- **Open tasks**: Display the number of open to-dos, reminders, or items in a shopping cart.
- **Automatic reset**: Clear the counter automatically when the user resumes the app using the `autoClear` configuration option.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-badge` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-badge
npx cap sync
```

### Android

#### 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:

- `$shortcutBadgerVersion` version of `me.leolin:ShortcutBadger` (default: `1.1.22`)

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

### iOS

#### Privacy manifest

Add the `NSPrivacyAccessedAPICategoryUserDefaults` dictionary key to your [Privacy Manifest](https://capacitorjs.com/docs/ios/privacy-manifest) (usually `ios/App/PrivacyInfo.xcprivacy`):

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>
```

## Configuration

These configuration values are available:

| Prop            | Type      | Description                                                                                                                                                                  | Default |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **`persist`**   | `boolean` | Configure whether the plugin should restore the counter after a reboot or app restart. Only available on Android and iOS.                                                    | `true`  |
| **`autoClear`** | `boolean` | Configure whether the plugin should reset the counter after resuming the application. On **iOS**, this will also clear all notifications. Only available on Android and iOS. | `false` |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "Badge": {
      "persist": true,
      "autoClear": false
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-badge" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Badge: {
      persist: true,
      autoClear: false,
    },
  },
};

export default config;
```

## Usage

The following examples show how to get, set, increase, decrease, and clear the badge count, check whether badges are supported, and check and request permissions.

### Get the current badge count

Read the current badge count. The count won't be lost after a reboot or app restart:

```
import { Badge } from '@capawesome/capacitor-badge';

const get = async () => {
  const result = await Badge.get();
  return result.count;
};
```

### Set the badge count

Set the badge count to a specific value. On iOS, setting the count to `0` will remove the badge and also clear all notifications:

```
import { Badge } from '@capawesome/capacitor-badge';

const set = async (count: number) => {
  await Badge.set({ count });
};
```

### Increase or decrease the badge count

Increment or decrement the badge count by one, for example when a new message arrives or is read:

```
import { Badge } from '@capawesome/capacitor-badge';

const increase = async () => {
  await Badge.increase();
};

const decrease = async () => {
  await Badge.decrease();
};
```

### Clear the badge count

Remove the badge from the app icon. On iOS, this will also clear all notifications:

```
import { Badge } from '@capawesome/capacitor-badge';

const clear = async () => {
  await Badge.clear();
};
```

### Check if badges are supported

Check whether the badge count is supported on the current device, for example since not every Android launcher supports badges:

```
import { Badge } from '@capawesome/capacitor-badge';

const isSupported = async () => {
  const result = await Badge.isSupported();
  return result.isSupported;
};
```

### Check and request permissions

Check and request the permission to display the badge:

```
import { Badge } from '@capawesome/capacitor-badge';

const checkPermissions = async () => {
  const result = await Badge.checkPermissions();
};

const requestPermissions = async () => {
  const result = await Badge.requestPermissions();
};
```

## API

- [`get()`](#get)
- [`set(...)`](#set)
- [`increase()`](#increase)
- [`decrease()`](#decrease)
- [`clear()`](#clear)
- [`isSupported()`](#issupported)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### get()

```
get() => Promise<GetBadgeResult>
```

Get the badge count. The badge count won't be lost after a reboot or app restart.

Default: `0`.

**Returns:** `Promise<GetBadgeResult>`

______________________________________________________________________

### set(...)

```
set(options: SetBadgeOptions) => Promise<void>
```

Set the badge count.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetBadgeOptions` |

______________________________________________________________________

### increase()

```
increase() => Promise<void>
```

Increase the badge count.

______________________________________________________________________

### decrease()

```
decrease() => Promise<void>
```

Decrease the badge count.

______________________________________________________________________

### clear()

```
clear() => Promise<void>
```

Clear the badge count.

On **iOS**, this will remove the badge and also clear all notifications.

______________________________________________________________________

### isSupported()

```
isSupported() => Promise<IsSupportedResult>
```

Check if the badge count is supported.

**Returns:** `Promise<IsSupportedResult>`

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permission to display badge.

**Returns:** `Promise<PermissionStatus>`

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to display badge.

**Returns:** `Promise<PermissionStatus>`

______________________________________________________________________

### Interfaces

#### GetBadgeResult

| Prop        | Type     |
| ----------- | -------- |
| **`count`** | `number` |

#### SetBadgeOptions

| Prop        | Type     | Description                                                                                                          |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| **`count`** | `number` | The badge count to set. On **iOS**, setting the count to `0` will remove the badge and also clear all notifications. |

#### IsSupportedResult

| Prop              | Type      |
| ----------------- | --------- |
| **`isSupported`** | `boolean` |

#### PermissionStatus

| Prop          | Type              | Description                               |
| ------------- | ----------------- | ----------------------------------------- |
| **`display`** | `PermissionState` | Permission state of displaying the badge. |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

## Quirks

On **Android** there is no official API to set a badge, so not all launchers support badges. This plugin uses [ShortcutBadger](https://github.com/leolin310148/ShortcutBadger), which relies on vendor-specific mechanisms. All supported launchers are listed [there](https://github.com/leolin310148/ShortcutBadger#supported-launchers). On stock Android launchers, such as the Pixel Launcher, no badge is displayed.

On **Web**, the app must run as an installed PWA (in the taskbar or dock).

## FAQ

### Why is the badge not showing on my Android device?

Android provides no official API to set a badge on the launcher icon. This plugin therefore uses [ShortcutBadger](https://github.com/leolin310148/ShortcutBadger) under the hood, which relies on vendor-specific mechanisms offered by some manufacturers (such as Samsung, Xiaomi, HTC and Sony). Only the launchers listed as [supported launchers](https://github.com/leolin310148/ShortcutBadger#supported-launchers) can display the badge. On stock Android launchers, most notably the Pixel Launcher, no badge is displayed. You can use the `isSupported()` method to check whether badges are supported on the current device.

### Can the plugin display an Android notification badge (dot) instead?

No. Since Android 8.0, the launcher displays a [notification badge](https://developer.android.com/develop/ui/views/notifications/badges) only while the app has an *active* notification. The badge is derived from that notification and disappears as soon as the notification is dismissed, so it cannot be set independently of one. On stock Android it is also a dot without a count. If your app already displays notifications, the badge is shown automatically without any plugin call.

### Does the badge count persist after a reboot or app restart?

Yes, by default the badge count is restored after a reboot or app restart. You can disable this behavior by setting the `persist` configuration option to `false`, see the [Configuration](#configuration) section.

### How can I automatically clear the badge when the app is resumed?

Set the `autoClear` configuration option to `true` to reset the counter after resuming the application. Note that on iOS, this will also clear all notifications. See the [Configuration](#configuration) section for an example.

### Why does `checkPermissions()` always return `granted` on Android and Web?

Only iOS requires a permission to display a badge. On Android and Web no permission is needed, so the permission state is always `granted`.

### Why does clearing the badge also remove my notifications on iOS?

On iOS, calling `clear()` or setting the badge count to `0` removes the badge and also clears all notifications. This is platform behavior and cannot be changed by the plugin.

### Does this plugin work on the Web?

Yes, but the app must run as an installed PWA (in the taskbar or dock). Also make sure to check whether the browser supports badges using the `isSupported()` method.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Icon](https://capawesome.io/docs/sdks/capacitor/app-icon/): Change the app icon at runtime.
- [App Shortcuts](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/): Manage app shortcuts and quick actions.
- [Firebase Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/): Receive push notifications via Firebase Cloud Messaging.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/badge/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/badge/LICENSE).

## Credits

This plugin is based on the [Capacitor Badge](https://github.com/capawesome-team/capacitor-badge) plugin. Thanks to everyone who contributed to the project!

# Capacitor Barcode Scanner Plugin

Capacitor plugin for scanning barcodes and QR codes with a themeable fullscreen scanner or an embedded camera view on Android, iOS, and Web.

## Features

The Capacitor Barcode Scanner plugin provides a premium barcode scanning experience with two presentation modes. Here are some of the key features:

- 🖥️ **Ready-Made UI**: Fullscreen scanner with viewfinder, torch and flip camera buttons.
- 🎨 **Themeable**: Customize the accent color, title, instructions, and buttons of the scanner UI.
- 📦 **Batch Scanning**: Collect multiple barcodes in one session before returning them all at once.
- 🖼️ **Embedded View**: Render the camera natively inside any frame of your app layout.
- ⏯️ **Pause & Resume**: Pause and resume the barcode detection without stopping the camera.
- 🔦 **Torch & Zoom**: Control the flashlight and the camera zoom during a scan session.
- 🎯 **Detection Area**: Restrict the barcode detection to a region of interest.
- 🔁 **Deduplication**: Configurable timeout before the same barcode is emitted again.
- 🏷️ **13 Barcode Formats**: QR code, Aztec, Codabar, Code 39, Code 93, Code 128, Data Matrix, EAN-8, EAN-13, ITF, PDF417, UPC-A, and UPC-E.
- 📷 **Image Reading**: Read barcodes from image files.
- 🍎 **Zero Dependencies on iOS**: Built on AVFoundation and Vision only, so there are no third-party pods and no simulator issues.
- 🤖 **Offline on Android**: Uses the bundled ML Kit model, so scanning works offline and without Google Play services.
- 🌐 **Web Support**: Embedded scanning and image reading via the `BarcodeDetector` API.
- 🤝 **Compatibility**: Works hand in hand with the [Document Scanner](https://capawesome.io/docs/sdks/capacitor/document-scanner/), [Torch](https://capawesome.io/docs/sdks/capacitor/torch/) and [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Barcode Scanner plugin is typically used whenever an app needs to capture barcode or QR code data, for example:

- **Retail and inventory**: Scan product barcodes for stock management or price lookup.
- **Ticketing and events**: Validate QR codes on tickets, also in batch mode at the entrance.
- **Logistics**: Scan parcel labels (Code 128, ITF, PDF417) in a continuous embedded scanner.
- **Payments and links**: Let users scan QR codes to open links or initiate payments.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Embedded Barcode Scanner with Camera Preview in Capacitor](https://capawesome.io/blog/capacitor-embedded-barcode-scanner/): Render the camera preview natively inside your app layout, without transparent web view hacks.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-barcode-scanner` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-barcode-scanner
npx cap sync
```

### Android

The plugin declares the camera permission in its own manifest, so no manifest changes are required.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### Variables

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

- `$androidxCameraVersion` version of the `androidx.camera` dependencies (default: `1.6.1`)
- `$mlkitBarcodeScanningVersion` version of `com.google.mlkit:barcode-scanning` (default: `17.3.0`)

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

The plugin uses the **bundled** ML Kit barcode scanning model. Scanning works offline and does not require Google Play services, but the model increases your app size by a few megabytes. The default dependency versions are compatible with the 16 KB page size requirement of Google Play.

### iOS

Add the `NSCameraUsageDescription` key to the `Info.plist` file of your app to explain why your app needs access to the camera:

```
<key>NSCameraUsageDescription</key>
<string>The app needs access to the camera to scan barcodes.</string>
```

If the key is missing, `scan(...)` and `startScan(...)` reject with a clear error message.

### Web

The web implementation is based on the [BarcodeDetector](https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector) API, which is not available in all browsers. For browsers without built-in support, we recommend the [barcode-detector](https://www.npmjs.com/package/barcode-detector) polyfill:

```
import 'barcode-detector/side-effects';
```

The polyfill is intentionally **not** bundled with this plugin, so you stay in control of your bundle size.

## Configuration

No configuration required for this plugin.

## Usage

The plugin offers two presentation modes: a ready-made, themeable native fullscreen scanner (`scan(...)`) and an embedded camera view that is rendered natively inside a frame of your app layout (`startScan(...)`). The following examples show how to check the availability and permissions, scan barcodes with both modes, and read barcodes from image files.

### Check the availability and permissions

Check whether barcode scanning is available on the device and request the camera permission before you start a scan session:

```
import { BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

const isAvailable = async () => {
  const { available } = await BarcodeScanner.isAvailable();
  return available;
};

const requestPermissions = async () => {
  const { camera } = await BarcodeScanner.requestPermissions();
  return camera;
};
```

Get the cameras available on the device, for example to hide or disable a camera flip button if the device has only one camera:

```
import {
  BarcodeScanner,
  LensFacing,
} from '@capawesome-team/capacitor-barcode-scanner';

const canFlipCamera = async () => {
  const { lensFacings } = await BarcodeScanner.getAvailableCameras();
  return (
    lensFacings.includes(LensFacing.Back) &&
    lensFacings.includes(LensFacing.Front)
  );
};
```

If the user has denied the camera permission, open the native app settings page so that the user can grant it:

```
import { BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

const openSettings = async () => {
  await BarcodeScanner.openSettings();
};
```

### Scan a barcode with the fullscreen scanner

Open the ready-made fullscreen scanner and customize its user interface. Only barcodes that are fully inside the viewfinder are detected. The promise resolves with the first detected barcode:

```
import {
  BarcodeFormat,
  BarcodeScanner,
} from '@capawesome-team/capacitor-barcode-scanner';

const scanSingleBarcode = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    formats: [BarcodeFormat.QrCode, BarcodeFormat.Ean13],
    ui: {
      accentColor: '#59C7F9',
      instructions: 'Point your camera at a barcode.',
      title: 'Scan Barcode',
    },
  });
  return barcodes[0];
};
```

### Scan multiple barcodes in one session

Enable the batch mode to let the user collect multiple barcodes. The promise resolves with all of them when the user taps the done button:

```
import { BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

const scanMultipleBarcodes = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    batch: true,
  });
  return barcodes;
};
```

### Scan barcodes with the embedded camera view

Start an embedded scan session to render the camera preview inside a frame of your app layout. Detected barcodes are emitted continuously via the `barcodesScanned` event until you call `stopScan()`.

The camera preview is a **native view**. By default, it is rendered **above** the web view, which means that HTML elements cannot overlap the camera preview. Use a placeholder element to reserve the space in your layout and to measure the frame:

```
import {
  BarcodeScanner,
  LensFacing,
} from '@capawesome-team/capacitor-barcode-scanner';

const getScanFrame = () => {
  const rect = document.querySelector('#scanner').getBoundingClientRect();
  return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
};

const startEmbeddedScan = async () => {
  await BarcodeScanner.addListener('barcodesScanned', (event) => {
    console.log('Scanned barcodes:', event.barcodes);
  });
  await BarcodeScanner.startScan({
    frame: getScanFrame(),
    lensFacing: LensFacing.Back,
  });
};

const stopEmbeddedScan = async () => {
  await BarcodeScanner.stopScan();
  await BarcodeScanner.removeAllListeners();
};
```

### Overlay HTML elements over the embedded camera view

Set `placement` to `PreviewPlacement.Behind` to render the camera preview **behind** the web view. This way, HTML elements can overlap the camera preview, for example to draw a viewfinder or detection markers.

The camera preview is only visible where your app is transparent. The placeholder element used to measure the frame, all its ancestors and the `body` must have a transparent background over the frame area:

```
body,
#scanner {
  background: transparent;
}
```

With Ionic Framework UI components, also set `--background: transparent` on the surrounding `ion-content` element.

```
import {
  BarcodeScanner,
  PreviewPlacement,
} from '@capawesome-team/capacitor-barcode-scanner';

const startEmbeddedScanBehindWebView = async () => {
  await BarcodeScanner.startScan({
    frame: getScanFrame(),
    placement: PreviewPlacement.Behind,
  });
};
```

### Update the frame of the embedded camera view

When the layout of your app changes (for example after an orientation change), update the frame of the active scan session:

```
import { BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

window.addEventListener('resize', async () => {
  await BarcodeScanner.setScanFrame({ frame: getScanFrame() });
});
```

### Read barcodes from an image

Read barcodes from an image file, for example from an image the user picked with the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugin:

```
import { BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

const readBarcodesFromImage = async (path: string) => {
  const { barcodes } = await BarcodeScanner.readBarcodesFromImage({
    path,
  });
  return barcodes;
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`getAvailableCameras()`](#getavailablecameras)
- [`getZoomRatioRange()`](#getzoomratiorange)
- [`isAvailable()`](#isavailable)
- [`openSettings()`](#opensettings)
- [`pauseScan()`](#pausescan)
- [`readBarcodesFromImage(...)`](#readbarcodesfromimage)
- [`requestPermissions()`](#requestpermissions)
- [`resumeScan()`](#resumescan)
- [`scan(...)`](#scan)
- [`setScanFrame(...)`](#setscanframe)
- [`setTorchEnabled(...)`](#settorchenabled)
- [`setZoomRatio(...)`](#setzoomratio)
- [`startScan(...)`](#startscan)
- [`stopScan()`](#stopscan)
- [`addListener('barcodesScanned', ...)`](#addlistenerbarcodesscanned-)
- [`addListener('scanError', ...)`](#addlistenerscanerror-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the current camera permission status.

On **Web**, the permission status is queried on a best-effort basis. Some browsers do not support the camera permission query and always return `prompt`.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### getAvailableCameras()

```
getAvailableCameras() => Promise<GetAvailableCamerasResult>
```

Get the cameras available on the device.

Use this, for example, to hide or disable a camera flip button if the device has only one camera.

Only available on Android and iOS.

**Returns:** `Promise<GetAvailableCamerasResult>`

**Since:** 0.1.1

______________________________________________________________________

### getZoomRatioRange()

```
getZoomRatioRange() => Promise<GetZoomRatioRangeResult>
```

Get the minimum and maximum zoom ratio supported by the camera.

The promise rejects with the `NOT_SCANNING` error code if no scan session started with `startScan(...)` is active.

Only available on Android and iOS.

**Returns:** `Promise<GetZoomRatioRangeResult>`

**Since:** 0.0.1

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether barcode scanning is available on the device.

On **Android** and **iOS**, this resolves to `true` if the device has a camera.

On **Web**, this resolves to `true` if the browser supports camera access and the `BarcodeDetector` API is available (natively or via a polyfill).

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.0.1

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the native app settings page so that the user can grant the camera permission.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### pauseScan()

```
pauseScan() => Promise<void>
```

Pause the barcode detection of the active scan session.

The camera preview stays visible but no more `barcodesScanned` events are emitted until `resumeScan()` is called.

The promise rejects with the `NOT_SCANNING` error code if no scan session is active.

**Since:** 0.0.1

______________________________________________________________________

### readBarcodesFromImage(...)

```
readBarcodesFromImage(options: ReadBarcodesFromImageOptions) => Promise<ReadBarcodesFromImageResult>
```

Read barcodes from an image file.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `ReadBarcodesFromImageOptions` |

**Returns:** `Promise<ReadBarcodesFromImageResult>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the camera permission.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### resumeScan()

```
resumeScan() => Promise<void>
```

Resume the barcode detection of the active scan session after it has been paused with `pauseScan()`.

The promise rejects with the `NOT_SCANNING` error code if no scan session is active.

**Since:** 0.0.1

______________________________________________________________________

### scan(...)

```
scan(options?: ScanOptions | undefined) => Promise<ScanResult>
```

Open the ready-made fullscreen scanner user interface.

In single-shot mode (default), the promise resolves with the first detected barcode. In batch mode, the user collects multiple barcodes and the promise resolves with all of them when the user taps the done button.

Only barcodes that are fully inside the viewfinder are detected.

The promise rejects with the `SCAN_CANCELED` error code if the user closes the scanner without a result.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ScanOptions` |

**Returns:** `Promise<ScanResult>`

**Since:** 0.0.1

______________________________________________________________________

### setScanFrame(...)

```
setScanFrame(options: SetScanFrameOptions) => Promise<void>
```

Update the frame of the active scan session, for example after an orientation change or when the layout of your app changes.

The promise rejects with the `NOT_SCANNING` error code if no scan session is active.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SetScanFrameOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setTorchEnabled(...)

```
setTorchEnabled(options: SetTorchEnabledOptions) => Promise<void>
```

Enable or disable the torch (flashlight) during an active scan session.

The promise rejects with the `NOT_SCANNING` error code if no scan session started with `startScan(...)` is active.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetTorchEnabledOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setZoomRatio(...)

```
setZoomRatio(options: SetZoomRatioOptions) => Promise<void>
```

Set the zoom ratio of the camera during an active scan session.

The promise rejects with the `NOT_SCANNING` error code if no scan session started with `startScan(...)` is active.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SetZoomRatioOptions` |

**Since:** 0.0.1

______________________________________________________________________

### startScan(...)

```
startScan(options: StartScanOptions) => Promise<void>
```

Start an embedded scan session.

The camera preview is rendered natively in the given frame. Use a placeholder element to measure the frame (e.g. with `getBoundingClientRect()`) and reserve the space in your layout.

By default, the camera preview is rendered **above** the web view so that HTML elements cannot overlap it. Set `placement` to `PreviewPlacement.Behind` to render the camera preview **behind** the web view so that HTML elements can overlap it (see the `placement` property for the requirements).

Detected barcodes are emitted via the `barcodesScanned` event until `stopScan()` is called.

The promise rejects with the `ALREADY_SCANNING` error code if a scan session is already active.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `StartScanOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopScan()

```
stopScan() => Promise<void>
```

Stop the active scan session and remove the camera preview.

The promise rejects with the `NOT_SCANNING` error code if no scan session is active.

**Since:** 0.0.1

______________________________________________________________________

### addListener('barcodesScanned', ...)

```
addListener(eventName: 'barcodesScanned', listenerFunc: (event: BarcodesScannedEvent) => void) => Promise<PluginListenerHandle>
```

Called when barcodes are detected during an active scan session.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'barcodesScanned'`                     |
| **`listenerFunc`** | `(event: BarcodesScannedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('scanError', ...)

```
addListener(eventName: 'scanError', listenerFunc: (event: ScanErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during an active scan session.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'scanError'`                     |
| **`listenerFunc`** | `(event: ScanErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop         | Type              | Description                  | Since |
| ------------ | ----------------- | ---------------------------- | ----- |
| **`camera`** | `PermissionState` | The camera permission state. | 0.0.1 |

#### GetAvailableCamerasResult

| Prop              | Type           | Description                                              | Since |
| ----------------- | -------------- | -------------------------------------------------------- | ----- |
| **`lensFacings`** | `LensFacing[]` | The lens facings of the cameras available on the device. | 0.1.1 |

#### GetZoomRatioRangeResult

| Prop      | Type     | Description             | Since |
| --------- | -------- | ----------------------- | ----- |
| **`max`** | `number` | The maximum zoom ratio. | 0.0.1 |
| **`min`** | `number` | The minimum zoom ratio. | 0.0.1 |

#### IsAvailableResult

| Prop            | Type      | Description                                                 | Since |
| --------------- | --------- | ----------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not barcode scanning is available on the device. | 0.0.1 |

#### ReadBarcodesFromImageResult

| Prop           | Type        | Description            | Since |
| -------------- | ----------- | ---------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The detected barcodes. | 0.0.1 |

#### Barcode

| Prop               | Type                 | Description                                         | Since                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`bytes`**        | \`number[]           | null\`                                              | The raw bytes of the barcode. Only available on Android. On iOS and Web, this is always `null`.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **`cornerPoints`** | \`[number, number][] | null\`                                              | The four corner points of the barcode in clockwise order starting at the top-left corner. During an embedded scan session, the corner points are in CSS pixels relative to the top-left corner of the scan frame. During a fullscreen scan session, the corner points are in CSS pixels relative to the top-left corner of the screen. For `readBarcodesFromImage(...)`, the corner points are in pixels relative to the top-left corner of the image. This value might be `null` if the corner points cannot be determined. |
| **`displayValue`** | `string`             | The barcode value in a human-readable format.       | 0.0.1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **`format`**       | `BarcodeFormat`      | The format of the barcode.                          | 0.0.1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **`rawValue`**     | `string`             | The barcode value as it was encoded in the barcode. | 0.0.1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### ReadBarcodesFromImageOptions

| Prop          | Type              | Description                                                                                                                                  | Since |
| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`formats`** | `BarcodeFormat[]` | The barcode formats to detect. If not set, all supported formats are detected. Improve the performance by only setting the formats you need. | 0.0.1 |
| **`path`**    | `string`          | The path of the image file to read the barcodes from. On **Web**, this must be a URL that can be fetched by the browser.                     | 0.0.1 |

#### ScanResult

| Prop           | Type        | Description                                                                   | Since |
| -------------- | ----------- | ----------------------------------------------------------------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The scanned barcodes. In single-shot mode, this contains exactly one element. | 0.0.1 |

#### ScanOptions

| Prop             | Type              | Description                                                                                                                                                                                                                       | Default           | Since |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- |
| **`batch`**      | `boolean`         | Whether or not to scan multiple barcodes in one session. If `true`, the scanner collects the detected barcodes and resolves when the user taps the done button. If `false`, the scanner resolves with the first detected barcode. | `false`           | 0.0.1 |
| **`formats`**    | `BarcodeFormat[]` | The barcode formats to detect. If not set, all supported formats are detected. Improve the performance by only setting the formats you need.                                                                                      |                   | 0.0.1 |
| **`lensFacing`** | `LensFacing`      | The camera lens to use.                                                                                                                                                                                                           | `LensFacing.Back` | 0.0.1 |
| **`ui`**         | `ScanUiOptions`   | Options to customize the scanner user interface.                                                                                                                                                                                  |                   | 0.0.1 |

#### ScanUiOptions

| Prop                       | Type      | Description                                                                                                                                                     | Default | Since |
| -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`accentColor`**          | `string`  | The accent color of the scanner user interface as a hex color code (e.g. `#59C7F9`). The accent color is applied to the viewfinder corners and the done button. |         | 0.0.1 |
| **`beep`**                 | `boolean` | Whether or not to play a beep sound when a barcode is detected.                                                                                                 | `false` | 0.0.1 |
| **`hapticFeedback`**       | `boolean` | Whether or not to trigger a haptic feedback when a barcode is detected.                                                                                         | `true`  | 0.0.1 |
| **`instructions`**         | `string`  | The instructions text displayed below the title.                                                                                                                |         | 0.0.1 |
| **`showFlipCameraButton`** | `boolean` | Whether or not to show the flip camera button.                                                                                                                  | `false` | 0.0.1 |
| **`showTorchButton`**      | `boolean` | Whether or not to show the torch button.                                                                                                                        | `true`  | 0.0.1 |
| **`title`**                | `string`  | The title displayed at the top of the scanner user interface.                                                                                                   |         | 0.0.1 |

#### SetScanFrameOptions

| Prop        | Type        | Description                        | Since |
| ----------- | ----------- | ---------------------------------- | ----- |
| **`frame`** | `ScanFrame` | The new frame of the scan session. | 0.0.1 |

#### ScanFrame

| Prop         | Type     | Description                                                                                  | Since |
| ------------ | -------- | -------------------------------------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the frame in CSS pixels.                                                       | 0.0.1 |
| **`width`**  | `number` | The width of the frame in CSS pixels.                                                        | 0.0.1 |
| **`x`**      | `number` | The x coordinate of the frame in CSS pixels relative to the top-left corner of the viewport. | 0.0.1 |
| **`y`**      | `number` | The y coordinate of the frame in CSS pixels relative to the top-left corner of the viewport. | 0.0.1 |

#### SetTorchEnabledOptions

| Prop          | Type      | Description                         | Since |
| ------------- | --------- | ----------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether or not to enable the torch. | 0.0.1 |

#### SetZoomRatioOptions

| Prop        | Type     | Description                                                                                | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------ | ----- |
| **`ratio`** | `number` | The zoom ratio to set. Must be a value within the range returned by `getZoomRatioRange()`. | 0.0.1 |

#### StartScanOptions

| Prop                   | Type               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Default                  | Since |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |
| **`detectionArea`**    | `DetectionArea`    | The area within the scan frame in which barcodes are detected. Barcodes that are detected outside of this area are ignored. If not set, barcodes are detected in the entire scan frame.                                                                                                                                                                                                                                                                                                                                                     |                          | 0.0.1 |
| **`duplicateTimeout`** | `number`           | The time in milliseconds after which the same barcode is emitted again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `1500`                   | 0.0.1 |
| **`formats`**          | `BarcodeFormat[]`  | The barcode formats to detect. If not set, all supported formats are detected. Improve the performance by only setting the formats you need.                                                                                                                                                                                                                                                                                                                                                                                                |                          | 0.0.1 |
| **`frame`**            | `ScanFrame`        | The frame in which the camera preview is rendered. The coordinates are in CSS pixels relative to the top-left corner of the viewport.                                                                                                                                                                                                                                                                                                                                                                                                       |                          | 0.0.1 |
| **`lensFacing`**       | `LensFacing`       | The camera lens to use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `LensFacing.Back`        | 0.0.1 |
| **`placement`**        | `PreviewPlacement` | Where the camera preview is rendered relative to the web view. With [`PreviewPlacement.Above`](#previewplacement), HTML elements cannot overlap the camera preview. With [`PreviewPlacement.Behind`](#previewplacement), HTML elements can overlap the camera preview, for example to draw a viewfinder or detection markers. The camera preview is only visible where your app is transparent. The placeholder element used to measure the frame, all its ancestors and the `body` must have a transparent background over the frame area. | `PreviewPlacement.Above` | 0.0.1 |

#### DetectionArea

| Prop         | Type     | Description                                                                                             | Since |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the detection area in CSS pixels.                                                         | 0.0.1 |
| **`width`**  | `number` | The width of the detection area in CSS pixels.                                                          | 0.0.1 |
| **`x`**      | `number` | The x coordinate of the detection area in CSS pixels relative to the top-left corner of the scan frame. | 0.0.1 |
| **`y`**      | `number` | The y coordinate of the detection area in CSS pixels relative to the top-left corner of the scan frame. | 0.0.1 |

#### PluginListenerHandle

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

#### BarcodesScannedEvent

| Prop           | Type        | Description            | Since |
| -------------- | ----------- | ---------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The detected barcodes. | 0.0.1 |

#### ScanErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### LensFacing

| Members     | Value     | Description       | Since |
| ----------- | --------- | ----------------- | ----- |
| **`Back`**  | `'BACK'`  | The back camera.  | 0.0.1 |
| **`Front`** | `'FRONT'` | The front camera. | 0.0.1 |

#### BarcodeFormat

| Members          | Value           | Description                                                                           | Since |
| ---------------- | --------------- | ------------------------------------------------------------------------------------- | ----- |
| **`Aztec`**      | `'AZTEC'`       | Aztec barcode.                                                                        | 0.0.1 |
| **`Codabar`**    | `'CODABAR'`     | Codabar barcode. On **iOS**, this format is only detected by the camera on iOS 15.4+. | 0.0.1 |
| **`Code128`**    | `'CODE_128'`    | Code 128 barcode.                                                                     | 0.0.1 |
| **`Code39`**     | `'CODE_39'`     | Code 39 barcode.                                                                      | 0.0.1 |
| **`Code93`**     | `'CODE_93'`     | Code 93 barcode.                                                                      | 0.0.1 |
| **`DataMatrix`** | `'DATA_MATRIX'` | Data Matrix barcode.                                                                  | 0.0.1 |
| **`Ean13`**      | `'EAN_13'`      | EAN-13 barcode.                                                                       | 0.0.1 |
| **`Ean8`**       | `'EAN_8'`       | EAN-8 barcode.                                                                        | 0.0.1 |
| **`Itf`**        | `'ITF'`         | ITF (Interleaved 2 of 5) barcode.                                                     | 0.0.1 |
| **`Pdf417`**     | `'PDF_417'`     | PDF417 barcode.                                                                       | 0.0.1 |
| **`QrCode`**     | `'QR_CODE'`     | QR code.                                                                              | 0.0.1 |
| **`UpcA`**       | `'UPC_A'`       | UPC-A barcode.                                                                        | 0.0.1 |
| **`UpcE`**       | `'UPC_E'`       | UPC-E barcode.                                                                        | 0.0.1 |

#### PreviewPlacement

| Members      | Value      | Description                                         | Since |
| ------------ | ---------- | --------------------------------------------------- | ----- |
| **`Above`**  | `'ABOVE'`  | The camera preview is rendered above the web view.  | 0.0.1 |
| **`Behind`** | `'BEHIND'` | The camera preview is rendered behind the web view. | 0.0.1 |

## Supported Barcode Formats

| Format        | Android | iOS  | Web ¹ |
| ------------- | ------- | ---- | ----- |
| `AZTEC`       | ✅      | ✅   | ✅    |
| `CODABAR`     | ✅      | ✅ ² | ✅    |
| `CODE_39`     | ✅      | ✅   | ✅    |
| `CODE_93`     | ✅      | ✅   | ✅    |
| `CODE_128`    | ✅      | ✅   | ✅    |
| `DATA_MATRIX` | ✅      | ✅   | ✅    |
| `EAN_8`       | ✅      | ✅   | ✅    |
| `EAN_13`      | ✅      | ✅   | ✅    |
| `ITF`         | ✅      | ✅   | ✅    |
| `PDF_417`     | ✅      | ✅   | ✅    |
| `QR_CODE`     | ✅      | ✅   | ✅    |
| `UPC_A`       | ✅      | ✅ ³ | ✅    |
| `UPC_E`       | ✅      | ✅   | ✅    |

¹ On the web, the supported formats depend on the browser (or the polyfill).

² Camera scanning of Codabar barcodes requires iOS 15.4+. Reading Codabar barcodes from images works on all supported iOS versions.

³ Apple's frameworks report UPC-A barcodes as EAN-13 barcodes with a leading `0`. The plugin normalizes them to `UPC_A` (unless you explicitly request only `EAN_13`), so the behavior is consistent across platforms.

## Migration from ML Kit Barcode Scanning

If you are migrating from the [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/) plugin, the following table maps the most important APIs:

| `@capacitor-mlkit/barcode-scanning`       | `@capawesome-team/capacitor-barcode-scanner`       |
| ----------------------------------------- | -------------------------------------------------- |
| `scan()`                                  | `scan()` (fullscreen UI, now also with batch mode) |
| `startScan()` (transparent web view)      | `startScan()` (embedded native view with `frame`)  |
| `stopScan()`                              | `stopScan()`                                       |
| —                                         | `pauseScan()` / `resumeScan()`                     |
| `readBarcodesFromImage()`                 | `readBarcodesFromImage()`                          |
| `isSupported()`                           | `isAvailable()`                                    |
| `enableTorch()` / `disableTorch()`        | `setTorchEnabled({ enabled })`                     |
| `setZoomRatio()` / `getZoomRatio()`       | `setZoomRatio()` / `getZoomRatioRange()`           |
| `getMinZoomRatio()` / `getMaxZoomRatio()` | `getZoomRatioRange()`                              |
| `checkPermissions()`                      | `checkPermissions()`                               |
| `requestPermissions()`                    | `requestPermissions()`                             |
| `openSettings()`                          | `openSettings()`                                   |
| `isGoogleBarcodeScannerModuleAvailable()` | Not needed (the scanner UI is part of the plugin)  |
| `addListener('barcodesScanned')`          | `addListener('barcodesScanned')`                   |
| `addListener('scanError')`                | `addListener('scanError')`                         |

**Key differences**:

- The camera preview is rendered inside a frame you provide, by default **above** the web view. You no longer need to make your app transparent (`hideBackground()`) during a scan, and HTML can no longer accidentally cover the camera. If you want to overlay HTML elements, opt in to rendering the camera preview behind the web view with the `placement` option.
- The `barcode.cornerPoints` are relative to the scan frame (embedded mode) or the image (`readBarcodesFromImage(...)`), not to the screen.
- Structured payload parsing (e.g. WiFi credentials, vCard contacts, driver licenses) is not yet supported. The `rawValue` is always returned, so you can parse the payload yourself. This feature is planned as a fast-follow.

## FAQ

### How is this plugin different from other similar plugins?

It offers two presentation modes — a themeable, ready-made fullscreen scanner and a true embedded native camera view — plus batch scanning, pause/resume, torch and zoom control, a configurable detection area and reading barcodes from image files across 13 formats. On iOS it is built purely on AVFoundation and Vision, so there are no third-party pods, no Swift Package Manager limitations and no arm64 simulator issues. On Android it uses the bundled ML Kit model so scanning works offline, and on the web it uses the `BarcodeDetector` API — all through one fully typed, actively maintained API with dedicated support. If you only need a quick one-off scan, a minimal setup can be enough; if you want a polished UI, an embedded view and consistent behavior on Android, iOS and the Web, this plugin is designed for that.

### Why does the embedded camera view cover my HTML elements?

By default, the embedded camera preview is a native view that is rendered above the web view. This is a deliberate design decision: it avoids the "camera not showing" issue class of transparent web view approaches. If you need buttons or overlays, place them outside the scan frame, use the fullscreen `scan(...)` mode which provides a themeable native UI, or set the `placement` option to `PreviewPlacement.Behind` to render the camera preview behind the web view.

### Is the fullscreen scanner available on the web?

No. The `scan(...)` method as well as torch and zoom control are not available on the web. However, you can build your own web scanner UI on top of the embedded mode (`startScan(...)`), which is fully supported on the web via the `BarcodeDetector` API.

### Why is the `bytes` property always `null` on iOS and Web?

Apple's AVFoundation and the web `BarcodeDetector` API only expose the string value of a barcode. The raw bytes are only available on Android.

### Does scanning work offline?

Yes. On Android, the plugin uses the bundled ML Kit model. On iOS, it uses the built-in AVFoundation framework. No network connection or Google Play services module download is required.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Document Scanner](https://capawesome.io/docs/sdks/capacitor/document-scanner/): Scan documents with the native fullscreen scanner.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Pick images to read barcodes from.
- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning.
- [Torch](https://capawesome.io/docs/sdks/capacitor/torch/): Control the flashlight outside of a scan session.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barcode-scanner/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barcode-scanner/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barcode-scanner/LICENSE).

# Capacitor Barometer Plugin

Capacitor plugin to obtain the static air pressure, which is measured in hectopascals (hPa).

## Features

The Capacitor Barometer plugin is one of the most complete air pressure sensing solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📏 **Precise Measurements**: Get accurate air pressure readings in hectopascals (hPa).
- 🔄 **Real-time Updates**: Continuously monitor barometer changes with event listeners.
- 🔍 **Device Detection**: Check if barometer sensor is available on the device.
- 🔑 **Permissions**: Check and request barometer sensor permissions.
- 📊 **Additional Data**: Get relative altitude measurements.
- ⏱️ **Timestamps**: Each measurement includes precise timing information.
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Compass](https://capawesome.io/docs/sdks/capacitor/compass/) and [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Barometer plugin is typically used whenever an app needs to react to changes in air pressure, for example:

- **Weather apps**: Show the current air pressure and track pressure trends to indicate weather changes.
- **Altitude tracking**: Use the relative altitude on iOS to detect elevation changes, for example while hiking or climbing stairs.
- **Outdoor and fitness apps**: Combine the pressure readings with their timestamps to analyze elevation profiles during activities.
- **Sensor dashboards**: Display real-time barometer readings using continuous measurement updates.

## Compatibility

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

## Guides

- [Announcing the Capacitor Barometer Plugin](https://capawesome.io/blog/announcing-the-capacitor-barometer-plugin/)
- [Exploring the Capacitor Barometer API](https://capawesome.io/blog/exploring-the-capacitor-barometer-api/)
- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How to use pressure readings for faster-than-GPS elevation change detection in outdoor and hiking apps.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-barometer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-barometer
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSMotionUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts:

```
<key>NSMotionUsageDescription</key>
<string>The app needs to access the motion activity.</string>
```

## Usage

The following examples show how to check whether the barometer is available, request permissions, read the latest measurement, and listen for continuous measurement updates.

### Check if the barometer is available

Check whether the device has a barometer sensor before using the other methods:

```
import { Barometer } from '@capawesome-team/capacitor-barometer';

const isAvailable = async () => {
  const result = await Barometer.isAvailable();
  console.log('Barometer is available:', result.isAvailable);
};
```

### Check and request permissions

Check and request permission to access the barometer sensor. On iOS, make sure you have added the `NSMotionUsageDescription` key to your `Info.plist` file (see [Installation](#installation)):

```
import { Barometer } from '@capawesome-team/capacitor-barometer';

const checkPermissions = async () => {
  const status = await Barometer.checkPermissions();
  console.log('Barometer permission status:', status.barometer);
};

const requestPermissions = async () => {
  const status = await Barometer.requestPermissions();
  console.log('Barometer permission status after request:', status.barometer);
};
```

### Get the latest measurement

Get the most recent measurement from the barometer sensor. It contains the air pressure in hectopascals (hPa), the timestamp of the measurement and, on iOS, the relative altitude in meters:

```
import { Barometer } from '@capawesome-team/capacitor-barometer';

const getMeasurement = async () => {
  const { measurement } = await Barometer.getMeasurement();
  console.log('Pressure:', measurement.pressure, 'hPa');
  console.log('Relative Altitude:', measurement.relativeAltitude, 'm');
  console.log('Timestamp:', new Date(measurement.timestamp));
};
```

### Listen for measurement updates

Add a listener for the `measurement` event and start emitting measurements to monitor air pressure changes continuously. When you no longer need updates, stop them and remove your listeners:

```
import { Barometer } from '@capawesome-team/capacitor-barometer';

const startMeasurementUpdates = async () => {
  Barometer.addListener('measurement', (event) => {
    console.log('New measurement:', event);
  });
  await Barometer.startMeasurementUpdates();
};

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

## API

- [`getMeasurement()`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getMeasurement()

```
getMeasurement() => Promise<GetMeasurementResult>
```

Get the latest measurement.

This method returns the most recent measurement from the barometer sensor.

Only available on Android and iOS.

**Returns:** `Promise<Measurement>`

**Since:** 7.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the barometer sensor is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 7.0.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Starts emitting `measurement` events.

Only available on Android and iOS.

**Since:** 7.0.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stops emitting `measurement` events.

Only available on Android and iOS.

**Since:** 7.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check if the app has permission to access the barometer sensor.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to access the barometer sensor.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 7.0.0

______________________________________________________________________

### Interfaces

#### Measurement

| Prop                   | Type     | Description                                                       | Since |
| ---------------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`pressure`**         | `number` | The pressure in hPa (hectopascal).                                | 7.0.0 |
| **`relativeAltitude`** | `number` | The relative altitude in meters. Only available on iOS.           | 7.0.0 |
| **`timestamp`**        | `number` | The timestamp of the measurement in milliseconds since the epoch. | 7.0.0 |

#### IsAvailableResult

| Prop              | Type      | Description                                                        | Since |
| ----------------- | --------- | ------------------------------------------------------------------ | ----- |
| **`isAvailable`** | `boolean` | Indicates whether the barometer sensor is available on the device. | 7.0.0 |

#### PermissionStatus

| Prop            | Type                       | Description                         | Since |
| --------------- | -------------------------- | ----------------------------------- | ----- |
| **`barometer`** | `BarometerPermissionState` | The permission status of barometer. | 7.0.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetMeasurementResult

`Measurement`

#### BarometerPermissionState

`PermissionState | 'limited'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### MeasurementEvent

`Measurement`

## FAQ

### What unit is the air pressure measured in?

The plugin returns the static air pressure in hectopascals (hPa). Each measurement also includes a timestamp in milliseconds since the epoch.

### How can I measure altitude with this plugin?

On iOS, each measurement includes the relative altitude in meters in addition to the air pressure. On Android, only the air pressure is available. See the [usage example](#get-the-latest-measurement) above.

### What happens if the device does not have a barometer sensor?

You can check whether the barometer sensor is available on the device using the `isAvailable()` method. It is recommended to call this method before using the other methods of the plugin.

### Do I need any permissions to use the barometer?

The plugin provides the `checkPermissions()` and `requestPermissions()` methods to manage access to the barometer sensor. On iOS, you also need to add the `NSMotionUsageDescription` key to your `Info.plist` file as described in the [Installation](#installation) section.

### How do I monitor air pressure changes continuously?

Add a listener for the `measurement` event and call `startMeasurementUpdates()` to start receiving measurements. When you no longer need updates, call `stopMeasurementUpdates()` and remove your listeners with `removeAllListeners()`. See the [usage example](#listen-for-measurement-updates) above.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device's compass heading.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barometer/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barometer/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/barometer/LICENSE).

# Capacitor Battery Plugin

Capacitor plugin to access battery information.

## Features

The Capacitor Battery plugin is one of the most complete battery monitoring solutions for Capacitor apps. Here are some of the key features:

- 🔋 **Battery level**: Read the current battery level of the device.
- ⚡ **Battery state**: Read whether the device is charging, full or unplugged.
- 🪫 **Low power mode**: Read whether the low power mode is enabled.
- 👂 **Change events**: Listen for changes to the battery level, state and low power mode.
- 🌐 **Web support**: Read the battery level and state on supported browsers.
- 🤝 **Compatibility**: Works alongside the [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Battery plugin is typically used whenever an app should adapt its behavior to the device's power situation, for example:

- **Energy-aware features**: Reduce background work, animations, or sync frequency when the battery level is low.
- **Low power mode handling**: Disable power-hungry features when the user has enabled low power mode.
- **Charging-dependent tasks**: Only start heavy tasks such as large downloads while the device is charging.
- **Status display**: Show the current battery level and charging state inside your app, for example in a kiosk or fleet app.
- **Reacting to changes**: Warn the user when the battery level drops by listening for change events.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How battery state pairs with the Thermal State plugin to gate background work.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-battery` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-battery
npx cap sync
```

This plugin does not require any additional configuration or permissions on Android or iOS.

On the **Web**, the battery level and state are only available in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers). The low power mode is not available on the Web.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get the current battery level and state, check if low power mode is enabled, listen for battery changes, and remove all listeners.

### Get the current battery level

Read the current battery level of the device as a value between `0.0` and `1.0`:

```
import { Battery } from '@capawesome/capacitor-battery';

const getBatteryLevel = async () => {
  const { level } = await Battery.getBatteryLevel();
  return level;
};
```

### Get the current battery state

Check whether the device is charging, full or unplugged:

```
import { Battery } from '@capawesome/capacitor-battery';

const getBatteryState = async () => {
  const { state } = await Battery.getBatteryState();
  return state;
};
```

### Check if low power mode is enabled

Read whether the low power mode (power saver mode on Android, Low Power Mode on iOS) is currently enabled. Only available on Android and iOS:

```
import { Battery } from '@capawesome/capacitor-battery';

const isLowPowerModeEnabled = async () => {
  const { enabled } = await Battery.isLowPowerModeEnabled();
  return enabled;
};
```

### Listen for battery changes

Get notified when the battery level, battery state or low power mode changes. The device is only observed while at least one listener is attached. The `lowPowerModeChange` event is only available on Android and iOS:

```
import { Battery } from '@capawesome/capacitor-battery';

const addBatteryLevelChangeListener = async () => {
  await Battery.addListener('batteryLevelChange', event => {
    console.log('Battery level changed:', event.level);
  });
};

const addBatteryStateChangeListener = async () => {
  await Battery.addListener('batteryStateChange', event => {
    console.log('Battery state changed:', event.state);
  });
};

const addLowPowerModeChangeListener = async () => {
  await Battery.addListener('lowPowerModeChange', event => {
    console.log('Low power mode changed:', event.enabled);
  });
};
```

### Remove all listeners

Remove all listeners that were registered for this plugin:

```
import { Battery } from '@capawesome/capacitor-battery';

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

## API

- [`getBatteryLevel()`](#getbatterylevel)
- [`getBatteryState()`](#getbatterystate)
- [`isLowPowerModeEnabled()`](#islowpowermodeenabled)
- [`addListener('batteryLevelChange', ...)`](#addlistenerbatterylevelchange-)
- [`addListener('batteryStateChange', ...)`](#addlistenerbatterystatechange-)
- [`addListener('lowPowerModeChange', ...)`](#addlistenerlowpowermodechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getBatteryLevel()

```
getBatteryLevel() => Promise<GetBatteryLevelResult>
```

Get the current battery level of the device.

On the web, this is only supported in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers).

Only available on Android, iOS and Web.

**Returns:** `Promise<GetBatteryLevelResult>`

**Since:** 0.1.0

______________________________________________________________________

### getBatteryState()

```
getBatteryState() => Promise<GetBatteryStateResult>
```

Get the current battery state of the device.

On the web, this is only supported in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers).

Only available on Android, iOS and Web.

**Returns:** `Promise<GetBatteryStateResult>`

**Since:** 0.1.0

______________________________________________________________________

### isLowPowerModeEnabled()

```
isLowPowerModeEnabled() => Promise<IsLowPowerModeEnabledResult>
```

Get whether the low power mode is currently enabled.

On Android, this refers to the power saver mode. On iOS, this refers to the Low Power Mode.

Only available on Android and iOS.

**Returns:** `Promise<IsLowPowerModeEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('batteryLevelChange', ...)

```
addListener(eventName: 'batteryLevelChange', listenerFunc: (event: BatteryLevelChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the battery level of the device.

The device is only observed while at least one listener is attached.

On the web, this is only supported in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers).

Only available on Android, iOS and Web.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'batteryLevelChange'`                     |
| **`listenerFunc`** | `(event: BatteryLevelChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('batteryStateChange', ...)

```
addListener(eventName: 'batteryStateChange', listenerFunc: (event: BatteryStateChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the battery state of the device.

The device is only observed while at least one listener is attached.

On the web, this is only supported in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers).

Only available on Android, iOS and Web.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'batteryStateChange'`                     |
| **`listenerFunc`** | `(event: BatteryStateChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('lowPowerModeChange', ...)

```
addListener(eventName: 'lowPowerModeChange', listenerFunc: (event: LowPowerModeChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the low power mode of the device.

The device is only observed while at least one listener is attached.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'lowPowerModeChange'`                     |
| **`listenerFunc`** | `(event: LowPowerModeChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetBatteryLevelResult

| Prop        | Type     | Description                                                                 | Since |
| ----------- | -------- | --------------------------------------------------------------------------- | ----- |
| **`level`** | `number` | The current battery level of the device as a value between `0.0` and `1.0`. | 0.1.0 |

#### GetBatteryStateResult

| Prop        | Type           | Description                              | Since |
| ----------- | -------------- | ---------------------------------------- | ----- |
| **`state`** | `BatteryState` | The current battery state of the device. | 0.1.0 |

#### IsLowPowerModeEnabledResult

| Prop          | Type      | Description                                      | Since |
| ------------- | --------- | ------------------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether the low power mode is currently enabled. | 0.1.0 |

#### PluginListenerHandle

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

#### BatteryLevelChangeEvent

| Prop        | Type     | Description                                                                 | Since |
| ----------- | -------- | --------------------------------------------------------------------------- | ----- |
| **`level`** | `number` | The current battery level of the device as a value between `0.0` and `1.0`. | 0.1.0 |

#### BatteryStateChangeEvent

| Prop        | Type           | Description                              | Since |
| ----------- | -------------- | ---------------------------------------- | ----- |
| **`state`** | `BatteryState` | The current battery state of the device. | 0.1.0 |

#### LowPowerModeChangeEvent

| Prop          | Type      | Description                                      | Since |
| ------------- | --------- | ------------------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether the low power mode is currently enabled. | 0.1.0 |

### Type Aliases

#### BatteryState

The battery state of the device.

- `charging`: The device is plugged into power and the battery is charging.
- `full`: The device is plugged into power and the battery is fully charged.
- `unplugged`: The device is not plugged into power and the battery is discharging.
- `unknown`: The battery state could not be determined.

`'charging' | 'full' | 'unplugged' | 'unknown'`

## Battery Information

Keep the following platform differences in mind when accessing battery information:

- **Android**: The battery level and state are read from the sticky [`ACTION_BATTERY_CHANGED`](https://developer.android.com/reference/android/content/Intent#ACTION_BATTERY_CHANGED) broadcast. The low power mode reflects the [power saver mode](<https://developer.android.com/reference/android/os/PowerManager#isPowerSaveMode()>) of the device.
- **iOS**: The battery level is not available on the iOS Simulator, so `getBatteryLevel()` rejects with an error there. Use a real device to test this method. The low power mode reflects the [Low Power Mode](https://support.apple.com/en-us/101604) of the device.
- **Web**: The battery level and state are only available in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (Chromium-based browsers). The low power mode is not available on the Web.

## FAQ

### How is this plugin different from other similar plugins?

It reports the full battery picture — level, charging state, and low power mode — plus change events that observe the device only while a listener is attached, all through a fully typed API that works across Android, iOS, and supported browsers on the Web. If you just need a one-off battery reading, that's a quick call; if you want to react to charging and low-power changes over time without wasting energy, this plugin is built for exactly that.

### Why does `getBatteryLevel` fail on the iOS Simulator?

The battery level is not available on the iOS Simulator, so `getBatteryLevel()` rejects with an error there. Use a real device to test this method.

### Does this plugin work in all browsers?

No, on the Web the battery level and state are only available in browsers that implement the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API), which are Chromium-based browsers. The low power mode is not available on the Web at all.

### What is the range of the battery level value?

The battery level is returned as a value between `0.0` and `1.0`, where `0.0` means the battery is empty and `1.0` means it is fully charged. Multiply the value by 100 if you want to display it as a percentage.

### What does low power mode mean on Android and iOS?

On Android, it refers to the [power saver mode](<https://developer.android.com/reference/android/os/PowerManager#isPowerSaveMode()>) of the device. On iOS, it refers to the [Low Power Mode](https://support.apple.com/en-us/101604). The `isLowPowerModeEnabled()` method and the `lowPowerModeChange` event are only available on Android and iOS.

### Does listening for battery changes drain the battery?

The device is only observed while at least one listener is attached. As soon as you remove all listeners, for example with `removeAllListeners()`, the plugin stops observing the device.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions on Android.
- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, operating system, and memory.
- [Thermal State](https://capawesome.io/docs/sdks/capacitor/thermal-state/): Read the device thermal state and react before the operating system throttles your app.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/battery/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/battery/LICENSE).

# Capacitor Biometrics Plugin

Capacitor plugin to request biometric authentication, such as using face recognition or fingerprint recognition.

## Features

The Capacitor Biometrics plugin is one of the most complete biometric authentication solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 👁️ **Fingerprint, Face and Iris**: Supports fingerprint, face and iris recognition.
- 🔑 **Device Credential**: Optionally allow the user to authenticate using their device's credential (e.g., PIN, password) if biometric authentication is not available or fails.
- 🚨 **Error Codes**: Provides detailed error codes for better error handling.
- ✨ **Customizable**: Customize the authentication prompt with a title, subtitle, and button text.
- 🤝 **Compatibility**: Compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) and [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Biometrics plugin is typically used whenever an app needs to verify the identity of the user, for example:

- **App lock**: Require fingerprint or face authentication before the app or sensitive screens can be opened.
- **Confirming sensitive actions**: Ask the user to re-authenticate before critical actions such as payments or deleting data.
- **Protecting stored credentials**: Combine biometric authentication with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) or [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugin to guard tokens and passwords.
- **Device credential fallback**: Let users fall back to their device PIN or password when biometric authentication is not available or fails.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.5.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [capawesome-team/capacitor-biometrics-demo](https://github.com/capawesome-team/capacitor-biometrics-demo)

## Guides

- [Announcing the Capacitor Biometrics Plugin](https://capawesome.io/blog/announcing-the-capacitor-biometrics-plugin/)
- [Exploring the Capacitor Biometrics API](https://capawesome.io/blog/exploring-the-capacitor-biometrics-api/)
- [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/)

## Videos

- [How to use Biometrics in a Capacitor Mobile App](https://youtu.be/ixUvTX6n7x8?si=27_X3KiLGAkI9-vJ)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-biometrics` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-biometrics
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$androidxBiometricVersion` version of `androidx.biometric:biometric` (default: `1.1.0`)

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

### iOS

#### Privacy Descriptions

Add the `NSFaceIDUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the biometric authentication:

```
<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID for authentication.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether biometric authentication can be used, authenticate and cancel the user, prompt for enrollment, and query the device's biometric capabilities.

### Check if biometric authentication can be used

Before showing the authentication prompt, check whether biometrics is available on the device and has been configured by the current user. Only available on Android and iOS:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const isAvailable = async () => {
  const { isAvailable } = await Biometrics.isAvailable();
  return isAvailable;
};

const isEnrolled = async () => {
  const { isEnrolled } = await Biometrics.isEnrolled();
  return isEnrolled;
};
```

### Authenticate the user

Show a prompt asking the user to authenticate with their biometrics, with a customizable title, subtitle, and button texts. If the authentication succeeds, the promise resolves; if the user cancels or an error occurs, the promise rejects with a detailed error code. Only available on Android and iOS:

```
import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';

const authenticate = async () => {
  // If the user successfully authenticates, the promise resolves.
  // If the user cancels the authentication or if an error occurs, the promise rejects.
  try {
    await Biometrics.authenticate({
      title: 'Authentication Required',
      subtitle: 'Please authenticate to continue',
      cancelButtonText: 'Cancel',
      iosFallbackButtonText: 'Use Passcode',
      allowDeviceCredential: true,
    });
  } catch (error) {
    if (error.code === ErrorCode.USER_CANCELED) {
      console.log('User canceled the authentication.');
    } else if (error.code === ErrorCode.NOT_ENROLLED) {
      console.log('No biometric authentication enrolled.');
    } else if (error.code === ErrorCode.NOT_AVAILABLE) {
      console.log('Biometric authentication not available.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};
```

### Cancel an ongoing authentication

Cancel the ongoing authentication session and dismiss the prompt. Only available on Android (SDK 29+) and iOS:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const cancelAuthentication = async () => {
  await Biometrics.cancelAuthentication();
};
```

### Prompt the user to enroll their biometrics

If the user has not yet set up biometric authentication, you can prompt them to enroll. Only available on Android:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const enroll = async () => {
  await Biometrics.enroll();
};
```

### Check the device's biometric capabilities

Query the supported biometric strength level (only available on Android) and check whether the user has set up a device credential such as a PIN or password:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const getBiometricStrengthLevel = async () => {
  const { strengthLevel } = await Biometrics.getBiometricStrengthLevel();
  return strengthLevel;
};

const hasDeviceCredential = async () => {
  const { hasDeviceCredential } = await Biometrics.hasDeviceCredential();
  return hasDeviceCredential;
};
```

## API

- [`authenticate(...)`](#authenticate)
- [`cancelAuthentication()`](#cancelauthentication)
- [`enroll()`](#enroll)
- [`getAuthenticationType()`](#getauthenticationtype)
- [`getBiometricStrengthLevel()`](#getbiometricstrengthlevel)
- [`getBiometricType()`](#getbiometrictype)
- [`getBiometricTypes()`](#getbiometrictypes)
- [`hasDeviceCredential()`](#hasdevicecredential)
- [`isAllowed()`](#isallowed)
- [`isAvailable()`](#isavailable)
- [`isEnrolled()`](#isenrolled)
- [`isLockedOut()`](#islockedout)
- [Interfaces](#interfaces)
- [Enums](#enums)

### authenticate(...)

```
authenticate(options?: AuthenticateOptions | undefined) => Promise<void>
```

Authenticates the user locally using the device's biometric authentication.

This method will show a prompt to the user asking them to authenticate using their biometrics (e.g., fingerprint, face recognition). If the user successfully authenticates, the promise resolves. If the user cancels the authentication or if an error occurs, the promise rejects.

Rejects if another authentication is already in progress.

It is recommended to check if biometrics is available and enrolled using the `isAvailable()` and `isEnrolled()` methods before calling this method.

On **iOS**, the first time the user is prompted to authenticate, they will be asked for permission to use biometrics. If the user denies permission, the promise will reject with an error.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `AuthenticateOptions` |

**Since:** 0.1.0

______________________________________________________________________

### cancelAuthentication()

```
cancelAuthentication() => Promise<void>
```

Cancel the ongoing authentication session and dismisses the prompt.

This method is only available on Android (SDK 29+) and iOS.

**Since:** 7.0.0

______________________________________________________________________

### enroll()

```
enroll() => Promise<void>
```

Prompt the user to enroll their biometrics.

This method is only available on Android.

**Since:** 7.0.0

______________________________________________________________________

### getAuthenticationType()

```
getAuthenticationType() => Promise<GetAuthenticationTypeResult>
```

Check whether the user authenticated using a device credential or a biometric credential.

Only available on Android.

**Returns:** `Promise<GetAuthenticationTypeResult>`

**Since:** 0.2.0

______________________________________________________________________

### getBiometricStrengthLevel()

```
getBiometricStrengthLevel() => Promise<GetBiometricStrengthLevelResult>
```

Returns the biometric strength level of the device.

Only available on Android.

**Returns:** `Promise<GetBiometricStrengthLevelResult>`

**Since:** 0.1.0

______________________________________________________________________

### getBiometricType()

```
getBiometricType() => Promise<GetBiometricTypeResult>
```

Returns the type of biometric authentication available on the device.

If multiple biometric types are available, returns the highest priority type based on the following order: Face > Iris > Fingerprint.

Only available on Android and iOS.

**Returns:** `Promise<GetBiometricTypeResult>`

**Since:** 0.5.1

______________________________________________________________________

### getBiometricTypes()

```
getBiometricTypes() => Promise<GetBiometricTypesResult>
```

Returns all biometric authentication types available on the device.

On **iOS**, this returns at most a single-element array because the platform exposes only one biometric type per device.

If no biometric authentication is available, an empty array is returned.

Only available on Android and iOS.

**Returns:** `Promise<GetBiometricTypesResult>`

**Since:** 0.5.4

______________________________________________________________________

### hasDeviceCredential()

```
hasDeviceCredential() => Promise<HasDeviceCredentialResult>
```

Check whether or not the device's credential (e.g., PIN, password) has been set up by the current user of the device.

Only available on Android and iOS.

**Returns:** `Promise<HasDeviceCredentialResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAllowed()

```
isAllowed() => Promise<IsAllowedResult>
```

Check whether the user has granted permission to use biometric authentication.

On **Android**, biometrics have no OS-level permission gate, so this always resolves to `true`.

On **iOS**, this returns `false` only after the user has explicitly denied the Face ID permission prompt. Before the first `authenticate()` call it returns `true`, since iOS provides no API to distinguish the pre-prompt state from a granted state.

Only available on Android and iOS.

**Returns:** `Promise<IsAllowedResult>`

**Since:** 0.5.4

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether or not biometrics is available on the device.

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### isEnrolled()

```
isEnrolled() => Promise<IsEnrolledResult>
```

Check whether or not biometrics is available on the device and has been configured by the current user of the device.

Only available on Android and iOS.

**Returns:** `Promise<IsEnrolledResult>`

**Since:** 0.1.0

______________________________________________________________________

### isLockedOut()

```
isLockedOut() => Promise<IsLockedOutResult>
```

Check whether biometric authentication is currently locked out due to too many failed attempts.

On **Android**, the platform exposes no queryable lockout status. This returns `true` only if the most recent `authenticate()` call in the current process failed with a lockout error; the state is cleared on the next successful authentication or process restart.

Only available on Android and iOS.

**Returns:** `Promise<IsLockedOutResult>`

**Since:** 0.5.4

______________________________________________________________________

### Interfaces

#### AuthenticateOptions

| Prop                           | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Default                  | Since |
| ------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |
| **`allowDeviceCredential`**    | `boolean`           | Whether or not to allow the user to authenticate using their device's credential (e.g., PIN, password) if biometric authentication is not available or fails. You can check if the device's credential is set up using the `hasDeviceCredential()` method.                                                                                                                                                       | `false`                  | 0.1.0 |
| **`androidBiometricStrength`** | `BiometricStrength` | The Android biometric strength to use for authentication. You can check the supported biometric strength level of the device using the `getBiometricStrengthLevel()` method. **Note**: On Android API Level 28 and 29, this will always be set to `BiometricStrength.Weak` regardless of the value passed in if `allowDeviceCredential` is set to `true`. This is a known limitation. Only available on Android. | `BiometricStrength.Weak` | 0.1.0 |
| **`cancelButtonText`**         | `string`            | The negative button text of the authentication prompt.                                                                                                                                                                                                                                                                                                                                                           |                          | 0.1.0 |
| **`iosFallbackButtonText`**    | `string`            | The fallback button text of the authentication prompt. Only available on iOS.                                                                                                                                                                                                                                                                                                                                    |                          | 0.1.0 |
| **`subtitle`**                 | `string`            | The subtitle of the authentication prompt.                                                                                                                                                                                                                                                                                                                                                                       |                          | 0.1.0 |
| **`title`**                    | `string`            | The title of the authentication prompt.                                                                                                                                                                                                                                                                                                                                                                          |                          | 0.1.0 |

#### GetAuthenticationTypeResult

| Prop                     | Type                 | Description                                  | Since |
| ------------------------ | -------------------- | -------------------------------------------- | ----- |
| **`authenticationType`** | `AuthenticationType` | The type of authentication used by the user. | 0.2.0 |

#### GetBiometricStrengthLevelResult

| Prop                | Type                | Description                                           | Since |
| ------------------- | ------------------- | ----------------------------------------------------- | ----- |
| **`strengthLevel`** | `BiometricStrength` | The supported biometric strength level of the device. | 0.1.0 |

#### GetBiometricTypeResult

| Prop                | Type            | Description                                                   | Since |
| ------------------- | --------------- | ------------------------------------------------------------- | ----- |
| **`biometricType`** | `BiometricType` | The type of biometric authentication available on the device. | 0.5.1 |

#### GetBiometricTypesResult

| Prop        | Type              | Description                                                                                                    | Since |
| ----------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | ----- |
| **`types`** | `BiometricType[]` | The biometric authentication types available on the device. Empty if no biometric authentication is available. | 0.5.4 |

#### HasDeviceCredentialResult

| Prop                      | Type      | Description                                                                                                     | Since |
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | ----- |
| **`hasDeviceCredential`** | `boolean` | Whether or not the device's credential (e.g., PIN, password) has been set up by the current user of the device. | 0.1.0 |

#### IsAllowedResult

| Prop            | Type      | Description                                                                     | Since |
| --------------- | --------- | ------------------------------------------------------------------------------- | ----- |
| **`isAllowed`** | `boolean` | Whether or not the user has granted permission to use biometric authentication. | 0.5.4 |

#### IsAvailableResult

| Prop              | Type      | Description                                                         | Since |
| ----------------- | --------- | ------------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not biometric authentication is available on the device. | 0.1.0 |

#### IsEnrolledResult

| Prop             | Type      | Description                                                                                                     | Since |
| ---------------- | --------- | --------------------------------------------------------------------------------------------------------------- | ----- |
| **`isEnrolled`** | `boolean` | Whether or not biometrics is supported by the device and has been configured by the current user of the device. | 0.1.0 |

#### IsLockedOutResult

| Prop              | Type      | Description                                                                                      | Since |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------ | ----- |
| **`isLockedOut`** | `boolean` | Whether or not biometric authentication is currently locked out due to too many failed attempts. | 0.5.4 |

### Enums

#### BiometricStrength

| Members      | Value      | Since |
| ------------ | ---------- | ----- |
| **`Strong`** | `'STRONG'` | 0.1.0 |
| **`Weak`**   | `'WEAK'`   | 0.1.0 |

#### AuthenticationType

| Members                | Value                 | Description                                                                                                                                         | Since |
| ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Biometric`**        | `'BIOMETRIC'`         | The user authenticated using a biometric credential.                                                                                                | 0.2.0 |
| **`DeviceCredential`** | `'DEVICE_CREDENTIAL'` | The user authenticated using a device credential (e.g., PIN, password).                                                                             | 0.2.0 |
| **`Unknown`**          | `'UNKNOWN'`           | The user authenticated via an unknown method. This value may be returned on older Android versions due to partial incompatibility with a newer API. | 0.2.0 |

#### BiometricType

| Members           | Value           | Description                                                           | Since |
| ----------------- | --------------- | --------------------------------------------------------------------- | ----- |
| **`Face`**        | `'FACE'`        | Face authentication (Face ID on iOS, face recognition on Android).    | 0.5.1 |
| **`Fingerprint`** | `'FINGERPRINT'` | Fingerprint authentication (Touch ID on iOS, fingerprint on Android). | 0.5.1 |
| **`Iris`**        | `'IRIS'`        | Iris authentication. Only available on Android.                       | 0.5.1 |
| **`None`**        | `'NONE'`        | No biometric authentication available on the device.                  | 0.5.1 |

## FAQ

### Which biometric authentication methods are supported?

The plugin supports fingerprint, face, and iris recognition, where iris recognition is only available on Android. You can query the available methods on the device using the `getBiometricType()` and `getBiometricTypes()` methods.

### Can users authenticate with their device PIN or password instead?

Yes, set the `allowDeviceCredential` option of the `authenticate(...)` method to `true` to allow the user to authenticate with their device credential (e.g. PIN or password) if biometric authentication is not available or fails. You can check whether a device credential has been set up using the `hasDeviceCredential()` method.

### How do I check if biometric authentication is available before showing the prompt?

It is recommended to call the `isAvailable()` and `isEnrolled()` methods before calling `authenticate(...)`. This way you can check whether biometrics is available on the device and has been configured by the current user. See the [usage example](#check-if-biometric-authentication-can-be-used) above.

### How do I handle a failed or canceled authentication?

If the user cancels the authentication or an error occurs, the promise returned by `authenticate(...)` rejects with a detailed error code such as `USER_CANCELED`, `NOT_ENROLLED`, or `NOT_AVAILABLE`. See the [usage example](#authenticate-the-user) above for how to handle these error codes.

### What configuration is required on iOS?

You need to add the `NSFaceIDUsageDescription` key to your `Info.plist` file as described in the [Installation](#installation) section. The first time the user is prompted to authenticate, iOS will ask for permission to use biometrics; if the user denies it, the promise rejects with an error.

### How can I securely store credentials behind biometric authentication?

The plugin is compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) and [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugins, which can store sensitive key/value pairs. Check out the guide [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/) for a complete walkthrough.

## Related Plugins

- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.
- [Vault](https://capawesome.io/docs/sdks/capacitor/vault/): Securely store key/value pairs in lockable, biometric-protected vaults.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/LICENSE).

# Capacitor Bluetooth Low Energy Plugin

Capacitor plugin for Bluetooth Low Energy (BLE) communication in the central and peripheral role with advanced features like headless tasks, foreground services, and more.[1](#fn:1)[2](#fn:2)

## Features

The Capacitor Bluetooth Low Energy plugin is one of the most complete BLE communication solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🔄 **Central Role**: Communicate with BLE peripherals as a central device.
- 📳 **Peripheral Role**: Act as a BLE peripheral to communicate with other central devices.
- 📡 **Extended Advertising**: Advertise larger payloads with BLE 5.0+ extended advertising.
- 🦾 **Headless Task**: Add custom native code for specific events.
- 🌙 **Foreground Service**: Keep the connection alive even when the app is in the background.
- 🔌 **Auto Reconnection**: Automatically reconnect to peripherals when the connection is lost.
- ⏳ **Command Queue**: Queue up incoming commands to prevent operation failures.
- 📱 **Multiple Devices**: Connect to multiple devices at the same time.
- 🛠️ **Utils**: Utility functions to make your life easier.
- ⚔️ **Battle-Tested**: Used in more than 300 projects.
- 🤝 **Compatibility**: Works alongside the [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/), [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/) and [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Bluetooth Low Energy plugin is typically used to communicate with nearby BLE hardware, for example:

- **Connected hardware and IoT devices**: Connect to BLE peripherals such as sensors or wearables and exchange data by reading and writing characteristics.
- **Health and fitness apps**: Receive live measurements from devices like heart rate monitors via characteristic notifications.
- **Background data collection**: Keep the connection alive while the app is in the background using a foreground service on Android.
- **Device-to-device communication**: Act as a BLE peripheral and advertise your own services to other central devices.
- **Multi-device setups**: Connect to and communicate with multiple BLE devices at the same time.
- **Tap-to-pair onboarding**: Read a device's identifier from an [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/) tag, then connect to it over BLE — no manual scanning or pairing UI needed.

## Testimonials

> We migrated PadelBand, a sports tech app, from the Capacitor Community BLE plugin to this one and the difference is remarkable. The reliable background support and the ability to run custom native code with headless tasks made all the difference for our use case. Highly recommended!

-- [PadelBand](https://padel-band.com) Development Team

## 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     |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-heart-rate-monitor-app).

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor Bluetooth Low Energy Plugin](https://capawesome.io/blog/announcing-the-capacitor-bluetooth-low-energy-plugin/)
- [How to Build a Heart Rate Monitor with Capacitor](https://capawesome.io/blog/how-to-build-a-heart-rate-monitor-with-capacitor/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-bluetooth-low-energy` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-bluetooth-low-energy
npx cap sync
```

### Android

#### Features

Add the following element to your `AndroidManifest.xml` before or after the `application` tag:

```
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
```

Set the `android:required` attribute to `true` if your app can't function, or isn't designed to function, when Bluetooth Low Energy is not available on the device. If your app can function without Bluetooth Low Energy, set the `android:required` attribute to `false`. This will allow your app to be installed on devices that do not support Bluetooth Low Energy.

#### Permissions

This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if you want to support Android 11 and below. -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<!-- Required if you want to advertise as a BLE device. -->
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<!-- Required if you want to scan for BLE devices. -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Required if you want to be able to connect to paired Bluetooth devices. -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!--Required if you want to start a foreground service.-->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
```

You can read more about Bluetooth permissions in the [Android documentation](https://developer.android.com/develop/connectivity/bluetooth/bt-permissions).

#### Services

You also need to add the following service **inside** the `application` tag in your `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`):

```
<service android:name="io.capawesome.capacitorjs.plugins.bluetoothle.BluetoothLowEnergyService" android:foregroundServiceType="connectedDevice" />
```

#### Headless Task

If you want to run your own native code when a specific event occurs, you can create a headless task. For this, you need to create a Java class with the name `BluetoothLowEnergyHeadlessTask` in the same package as your `MainActivity`. Then implement the following methods:

```
import android.bluetooth.BluetoothGatt;
import android.bluetooth.BluetoothGattCharacteristic;
import android.bluetooth.BluetoothGattDescriptor;
import androidx.annotation.NonNull;

public class BluetoothLowEnergyHeadlessTask {
  public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic) {
    // Your code here
  }

  public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, @NonNull byte[] value) {
    // Your code here
  }

  public void onCharacteristicRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) {
    // Your code here
  }

  public void onCharacteristicWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) {
    // Your code here
  }

  public void onConnectionStateChange(@NonNull BluetoothGatt gatt, int status, int newState) {
    // Your code here
  }

  public void onDescriptorRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status, @NonNull byte[] value) {
    // Your code here
  }

  public void onDescriptorWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status) {
    // Your code here
  }

  public void onMtuChanged(@NonNull BluetoothGatt gatt, int mtu, int status) {
    // Your code here
  }

  public void onReadRemoteRssi(@NonNull BluetoothGatt gatt, int rssi, int status) {
    // Your code here
  }

  public void onServiceChanged(@NonNull BluetoothGatt gatt) {
    // Your code here
  }

  public void onServicesDiscovered(@NonNull BluetoothGatt gatt, int status) {
    // Your code here
  }
}
```

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSBluetoothAlwaysUsageDescription` key to the `Info.plist` file (usually `ios/App/App/Info.plist`), which tells the user why the app needs access to Bluetooth peripherals:

```
<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app needs access to Bluetooth peripherals to communicate with Bluetooth devices.</string>
```

#### Capabilities

If you want your app to maintain Bluetooth Low Energy connections in the background, ensure the `Background Modes` capability is enabled with `bluetooth-central` in your Xcode project. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize the plugin, manage permissions, scan for and connect to devices, discover services, read and write characteristics and descriptors, act as a peripheral, and listen for Bluetooth Low Energy events.

### Initialize the plugin

Initialize the plugin in the central or peripheral role and check whether Bluetooth Low Energy is available and enabled on the device:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const initialize = async () => {
  await BluetoothLowEnergy.initialize({ mode: 'central' });
};

const isAvailable = async () => {
  const result = await BluetoothLowEnergy.isAvailable();
  return result.isAvailable;
};

const isEnabled = async () => {
  const result = await BluetoothLowEnergy.isEnabled();
  return result.enabled;
};
```

### Check and request permissions

Check and request the required Bluetooth permissions. Only available on Android:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const checkPermissions = async () => {
  const result = await BluetoothLowEnergy.checkPermissions();
  return result;
};

const requestPermissions = async () => {
  const result = await BluetoothLowEnergy.requestPermissions();
  return result;
};
```

### Scan for devices

Start and stop scanning for nearby BLE devices. Scanned devices are delivered via the `deviceScanned` event (see [Listen for events](#listen-for-events)):

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startScan = async () => {
  await BluetoothLowEnergy.startScan();
};

const stopScan = async () => {
  await BluetoothLowEnergy.stopScan();
};
```

### Connect to a device

Connect to a BLE device by its ID, disconnect from it, and retrieve the currently connected devices:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const connect = async () => {
  await BluetoothLowEnergy.connect({ deviceId: '00:00:00:00:00:00' });
};

const disconnect = async () => {
  await BluetoothLowEnergy.disconnect({ deviceId: '00:00:00:00:00:00' });
};

const getConnectedDevices = async () => {
  const result = await BluetoothLowEnergy.getConnectedDevices();
  return result.devices;
};
```

### Bond with a device

Create a bond with a BLE device and check whether a device is already bonded. Only available on Android:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const createBond = async () => {
  await BluetoothLowEnergy.createBond({ deviceId: '00:00:00:00:00:00' });
};

const isBonded = async () => {
  const result = await BluetoothLowEnergy.isBonded({ deviceId: '00:00:00:00:00:00' });
  return result.bonded;
};
```

### Discover services

Discover the services of a connected device and retrieve them along with their characteristics and descriptors:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const discoverServices = async () => {
  await BluetoothLowEnergy.discoverServices({ deviceId: '00:00:00:00:00:00' });
};

const getServices = async () => {
  const result = await BluetoothLowEnergy.getServices({ deviceId: '00:00:00:00:00:00' });
  return result.services;
};
```

### Read and write characteristics

Read the value of a characteristic or write a new value to it:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readCharacteristic = async () => {
  const result = await BluetoothLowEnergy.readCharacteristic({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
  return result.value;
};

const writeCharacteristic = async () => {
  await BluetoothLowEnergy.writeCharacteristic({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};
```

### Read and write descriptors

Read the value of a descriptor or write a new value to it:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readDescriptor = async () => {
  const result = await BluetoothLowEnergy.readDescriptor({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    descriptorId: '00002902-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
  return result.value;
};

const writeDescriptor = async () => {
  await BluetoothLowEnergy.writeDescriptor({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    descriptorId: '00002902-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};
```

### Receive characteristic notifications

Start and stop notifications for a characteristic to get notified when its value changes. The new values are delivered via the `characteristicChanged` event (see [Listen for events](#listen-for-events)):

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startCharacteristicNotifications = async () => {
  await BluetoothLowEnergy.startCharacteristicNotifications({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
};

const stopCharacteristicNotifications = async () => {
  await BluetoothLowEnergy.stopCharacteristicNotifications({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
};
```

### Tune the connection

Read the signal strength (RSSI) of a connected device. On Android, you can also request a higher connection priority or a larger MTU for faster data transfers (`requestConnectionPriority(...)` and `requestMtu(...)` are only available on Android):

```
import { BluetoothLowEnergy, ConnectionPriority } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readRssi = async () => {
  const result = await BluetoothLowEnergy.readRssi({ deviceId: '00:00:00:00:00:00' });
  return result.rssi;
};

const requestConnectionPriority = async () => {
  await BluetoothLowEnergy.requestConnectionPriority({
    connectionPriority: ConnectionPriority.BALANCED,
    deviceId: '00:00:00:00:00:00',
  });
};

const requestMtu = async () => {
  await BluetoothLowEnergy.requestMtu({
    deviceId: '00:00:00:00:00:00',
    mtu: 512,
  });
};
```

### Act as a peripheral

Advertise your own services to nearby central devices in the peripheral role. Use `setCharacteristicValue(...)` to update the value of a characteristic (only available on Android):

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startAdvertising = async () => {
  await BluetoothLowEnergy.startAdvertising({
    manufacturerData: {
      0xffff: [1, 2, 3]
    },
    name: 'MyDevice',
    services: [
      {
        id: '0000180A-0000-1000-8000-00805F9B34FB',
        characteristics: [
          {
            id: '00002A29-0000-1000-8000-00805F9B34FB',
            descriptors: [], // Descriptors are ignored for now
            permissions: {
              read: true,
              write: true,
            },
            properties: {
              read: true,
              write: true,
              notify: true,
              indicate: true,
            },
          },
        ],
      },
    ],
  });
};

const setCharacteristicValue = async () => {
  await BluetoothLowEnergy.setCharacteristicValue({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};

const stopAdvertising = async () => {
  await BluetoothLowEnergy.stopAdvertising();
};
```

### Keep the connection alive in the background

Start a foreground service to keep the connection alive while the app is in the background. Only available on Android (see [Installation](#installation) for the required service declaration and permissions):

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startForegroundService = async () => {
  await BluetoothLowEnergy.startForegroundService({
    body: 'Body',
    id: 1,
    smallIcon: 'smallIcon',
    title: 'Title',
  });
};

const stopForegroundService = async () => {
  await BluetoothLowEnergy.stopForegroundService();
};
```

### Open system settings

Open the app settings, Bluetooth settings, or location settings so the user can grant permissions or enable Bluetooth. `openBluetoothSettings()` and `openLocationSettings()` are only available on Android:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const openAppSettings = async () => {
  await BluetoothLowEnergy.openAppSettings();
};

const openBluetoothSettings = async () => {
  await BluetoothLowEnergy.openBluetoothSettings();
};

const openLocationSettings = async () => {
  await BluetoothLowEnergy.openLocationSettings();
};
```

### Listen for events

Listen for plugin events such as scanned, connected, and disconnected devices or changed characteristic values, and remove the listeners when they are no longer needed:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const addListener = () => {
  BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
    console.log('Characteristic changed', event);
  });

  BluetoothLowEnergy.addListener('characteristicWriteRequest', async (event) => {
    console.log('Characteristic write request', event);
  });

  BluetoothLowEnergy.addListener('deviceConnected', (event) => {
    console.log('Device connected', event);
  });

  BluetoothLowEnergy.addListener('deviceDisconnected', (event) => {
    console.log('Device disconnected', event);
  });

  BluetoothLowEnergy.addListener('deviceScanned', (event) => {
    console.log('Device scanned', event);
  });
};

const removeAllListeners = () => {
  BluetoothLowEnergy.removeAllListeners();
};
```

### Convert byte arrays

Use the `BluetoothLowEnergyUtils` class to convert byte arrays to hexadecimal strings (see [Utils](#utils) for more information):

```
import { BluetoothLowEnergyUtils } from '@capawesome-team/capacitor-bluetooth-low-energy';

const convertBytesToHex = (bytes: number[]) => {
  return BluetoothLowEnergyUtils.convertBytesToHex({ bytes });
};
```

## API

- [`connect(...)`](#connect)
- [`createBond(...)`](#createbond)
- [`disconnect(...)`](#disconnect)
- [`discoverServices(...)`](#discoverservices)
- [`getConnectedDevices()`](#getconnecteddevices)
- [`getServices(...)`](#getservices)
- [`initialize(...)`](#initialize)
- [`isAvailable()`](#isavailable)
- [`isBonded(...)`](#isbonded)
- [`isEnabled()`](#isenabled)
- [`isExtendedAdvertisingAvailable()`](#isextendedadvertisingavailable)
- [`isLocationEnabled()`](#islocationenabled)
- [`openAppSettings()`](#openappsettings)
- [`openBluetoothSettings()`](#openbluetoothsettings)
- [`openLocationSettings()`](#openlocationsettings)
- [`readCharacteristic(...)`](#readcharacteristic)
- [`readDescriptor(...)`](#readdescriptor)
- [`readRssi(...)`](#readrssi)
- [`requestConnectionPriority(...)`](#requestconnectionpriority)
- [`requestMtu(...)`](#requestmtu)
- [`setCharacteristicValue(...)`](#setcharacteristicvalue)
- [`startAdvertising(...)`](#startadvertising)
- [`startCharacteristicNotifications(...)`](#startcharacteristicnotifications)
- [`startForegroundService(...)`](#startforegroundservice)
- [`startScan(...)`](#startscan)
- [`stopAdvertising()`](#stopadvertising)
- [`stopCharacteristicNotifications(...)`](#stopcharacteristicnotifications)
- [`stopForegroundService()`](#stopforegroundservice)
- [`stopScan()`](#stopscan)
- [`writeCharacteristic(...)`](#writecharacteristic)
- [`writeDescriptor(...)`](#writedescriptor)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions(...)`](#requestpermissions)
- [`addListener('characteristicChanged', ...)`](#addlistenercharacteristicchanged-)
- [`addListener('characteristicWriteRequest', ...)`](#addlistenercharacteristicwriterequest-)
- [`addListener('deviceConnected', ...)`](#addlistenerdeviceconnected-)
- [`addListener('deviceDisconnected', ...)`](#addlistenerdevicedisconnected-)
- [`addListener('deviceScanned', ...)`](#addlistenerdevicescanned-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### connect(...)

```
connect(options: ConnectOptions) => Promise<void>
```

Connect to a BLE device.

If the device is already connected, the promise resolves without reconnecting.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ConnectOptions` |

**Since:** 6.0.0

______________________________________________________________________

### createBond(...)

```
createBond(options: CreateBondOptions) => Promise<void>
```

Create a bond with the BLE device.

Only available on Android.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `CreateBondOptions` |

**Since:** 6.0.0

______________________________________________________________________

### disconnect(...)

```
disconnect(options: DisconnectOptions) => Promise<void>
```

Disconnect from the BLE device.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DisconnectOptions` |

**Since:** 6.0.0

______________________________________________________________________

### discoverServices(...)

```
discoverServices(options: DiscoverServiceOptions) => Promise<void>
```

Discover services provided by the device.

On **iOS**, this operation may take up to 30 seconds.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `DiscoverServiceOptions` |

**Since:** 6.0.0

______________________________________________________________________

### getConnectedDevices()

```
getConnectedDevices() => Promise<GetConnectedDevicesResult>
```

Get a list of connected devices.

Only available on Android and iOS.

**Returns:** `Promise<GetConnectedDevicesResult>`

**Since:** 6.0.0

______________________________________________________________________

### getServices(...)

```
getServices(options: GetServicesOptions) => Promise<GetServicesResult>
```

Get a list of services provided by the device.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetServicesOptions` |

**Returns:** `Promise<GetServicesResult>`

**Since:** 6.0.0

______________________________________________________________________

### initialize(...)

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

Initialize the plugin. This method must be called before any other method.

On **iOS**, this will prompt the user for Bluetooth permissions. On **Android** and **Web**, this does nothing.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 6.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether or not Bluetooth Low Energy is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 7.3.0

______________________________________________________________________

### isBonded(...)

```
isBonded(options: IsBondedOptions) => Promise<IsBondedResult>
```

Check if the device is bonded.

Only available on Android.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `IsBondedOptions` |

**Returns:** `Promise<IsBondedResult>`

**Since:** 6.0.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Check if Bluetooth is enabled.

On **iOS**, requires the plugin to be initialized. Returns `false` if not initialized.

Only available on Android and iOS.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 6.0.0

______________________________________________________________________

### isExtendedAdvertisingAvailable()

```
isExtendedAdvertisingAvailable() => Promise<IsExtendedAdvertisingAvailableResult>
```

Check if extended advertising is available on the device.

Extended advertising (BLE 5.0+) allows for larger advertising payloads (up to ~250 bytes in a single packet or ~1650 bytes with chaining) compared to legacy advertising (~27-31 bytes).

On **Android**, Bluetooth must be enabled; otherwise this always resolves to `false`, even if the device supports extended advertising. Use `isEnabled()` to check whether Bluetooth is enabled.

On **iOS**, this always resolves to `false`, since extended advertisements cannot be transmitted via CoreBluetooth.

**Returns:** `Promise<IsExtendedAdvertisingAvailableResult>`

**Since:** 8.2.0

______________________________________________________________________

### isLocationEnabled()

```
isLocationEnabled() => Promise<IsLocationEnabledResult>
```

Check if location services are enabled.

Only available on Android.

**Returns:** `Promise<IsLocationEnabledResult>`

**Since:** 7.7.0

______________________________________________________________________

### openAppSettings()

```
openAppSettings() => Promise<void>
```

Open the Bluetooth settings on the device.

Only available on Android and iOS.

**Since:** 6.0.0

______________________________________________________________________

### openBluetoothSettings()

```
openBluetoothSettings() => Promise<void>
```

Open the Bluetooth settings on the device.

Only available on Android.

**Since:** 6.0.0

______________________________________________________________________

### openLocationSettings()

```
openLocationSettings() => Promise<void>
```

Open the location settings on the device.

Only available on Android.

**Since:** 6.0.0

______________________________________________________________________

### readCharacteristic(...)

```
readCharacteristic(options: ReadCharacteristicOptions) => Promise<ReadCharacteristicResult>
```

Read the value of a characteristic.

On iOS, reading a characteristic that is notifying also emits a `characteristicChanged` event.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `ReadCharacteristicOptions` |

**Returns:** `Promise<ReadCharacteristicResult>`

**Since:** 6.0.0

______________________________________________________________________

### readDescriptor(...)

```
readDescriptor(options: ReadDescriptorOptions) => Promise<ReadDescriptorResult>
```

Read the value of a descriptor.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `ReadDescriptorOptions` |

**Returns:** `Promise<ReadDescriptorResult>`

**Since:** 6.0.0

______________________________________________________________________

### readRssi(...)

```
readRssi(options: ReadRssiOptions) => Promise<ReadRssiResult>
```

Read the RSSI value of the device.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `ReadRssiOptions` |

**Returns:** `Promise<ReadRssiResult>`

**Since:** 6.0.0

______________________________________________________________________

### requestConnectionPriority(...)

```
requestConnectionPriority(options: RequestConnectionPriorityOptions) => Promise<void>
```

Request a connection priority.

Only available on Android.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `RequestConnectionPriorityOptions` |

**Since:** 6.0.0

______________________________________________________________________

### requestMtu(...)

```
requestMtu(options: RequestMtuOptions) => Promise<void>
```

Request an MTU size.

Only available on Android.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `RequestMtuOptions` |

**Since:** 6.0.0

______________________________________________________________________

### setCharacteristicValue(...)

```
setCharacteristicValue(options: SetCharacteristicValueOptions) => Promise<void>
```

Set the value of a characteristic.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `SetCharacteristicValueOptions` |

**Since:** 7.2.0

______________________________________________________________________

### startAdvertising(...)

```
startAdvertising(options: StartAdvertisingOptions) => Promise<void>
```

Start advertising as a BLE device.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `StartAdvertisingOptions` |

**Since:** 7.2.0

______________________________________________________________________

### startCharacteristicNotifications(...)

```
startCharacteristicNotifications(options: StartCharacteristicNotificationsOptions) => Promise<void>
```

Start listening for characteristic value changes. This will emit the `characteristicChanged` event when a value changes.

Only available on Android and iOS.

| Param         | Type                                      |
| ------------- | ----------------------------------------- |
| **`options`** | `StartCharacteristicNotificationsOptions` |

**Since:** 6.0.0

______________________________________________________________________

### startForegroundService(...)

```
startForegroundService(options?: StartForegroundServiceOptions | undefined) => Promise<void>
```

Start the foreground service and show a notification.

This method should be called when the app is moved to the background to keep the Bluetooth connections alive.

Only available on Android.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `StartForegroundServiceOptions` |

**Since:** 6.0.0

______________________________________________________________________

### startScan(...)

```
startScan(options?: StartScanOptions | undefined) => Promise<void>
```

Start scanning for BLE devices. This will emit the `deviceScanned` event when a device is found.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `StartScanOptions` |

**Since:** 6.0.0

______________________________________________________________________

### stopAdvertising()

```
stopAdvertising() => Promise<void>
```

Stop advertising as a BLE device.

Only available on Android and iOS.

**Since:** 7.2.0

______________________________________________________________________

### stopCharacteristicNotifications(...)

```
stopCharacteristicNotifications(options: StopCharacteristicNotificationsOptions) => Promise<void>
```

Stop listening for characteristic value changes.

Only available on Android and iOS.

| Param         | Type                                     |
| ------------- | ---------------------------------------- |
| **`options`** | `StopCharacteristicNotificationsOptions` |

**Since:** 6.0.0

______________________________________________________________________

### stopForegroundService()

```
stopForegroundService() => Promise<void>
```

Stop the foreground service and remove the notification.

This method should be called when the app is moved to the foreground since the foreground service is no longer needed.

Only available on Android.

**Since:** 6.0.0

______________________________________________________________________

### stopScan()

```
stopScan() => Promise<void>
```

Stop scanning for BLE devices.

Only available on Android and iOS.

**Since:** 6.0.0

______________________________________________________________________

### writeCharacteristic(...)

```
writeCharacteristic(options: WriteCharacteristicOptions) => Promise<void>
```

Write a value to a characteristic.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `WriteCharacteristicOptions` |

**Since:** 6.0.0

______________________________________________________________________

### writeDescriptor(...)

```
writeDescriptor(options: WriteDescriptorOptions) => Promise<void>
```

Write a value to a descriptor.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `WriteDescriptorOptions` |

**Since:** 6.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for the plugin.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(permissions?: BluetoothLowEnergyPluginPermission | undefined) => Promise<PermissionStatus>
```

Request permissions for the plugin.

Only available on Android.

| Param             | Type                                 |
| ----------------- | ------------------------------------ |
| **`permissions`** | `BluetoothLowEnergyPluginPermission` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('characteristicChanged', ...)

```
addListener(eventName: 'characteristicChanged', listenerFunc: (event: CharacteristicChangedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a characteristic value changes.

Only available on Android and iOS.

| Param              | Type                                          |
| ------------------ | --------------------------------------------- |
| **`eventName`**    | `'characteristicChanged'`                     |
| **`listenerFunc`** | `(event: CharacteristicChangedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('characteristicWriteRequest', ...)

```
addListener(eventName: 'characteristicWriteRequest', listenerFunc: (event: CharacteristicWriteRequestEvent) => void) => Promise<PluginListenerHandle>
```

Called when a characteristic write request is received.

Only available on Android.

| Param              | Type                                               |
| ------------------ | -------------------------------------------------- |
| **`eventName`**    | `'characteristicWriteRequest'`                     |
| **`listenerFunc`** | `(event: CharacteristicWriteRequestEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.2.0

______________________________________________________________________

### addListener('deviceConnected', ...)

```
addListener(eventName: 'deviceConnected', listenerFunc: (event: DeviceConnectedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a device is connected.

Only available on Android and iOS.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'deviceConnected'`                     |
| **`listenerFunc`** | `(event: DeviceConnectedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.1.0

______________________________________________________________________

### addListener('deviceDisconnected', ...)

```
addListener(eventName: 'deviceDisconnected', listenerFunc: (event: DeviceDisconnectedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a device is disconnected.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'deviceDisconnected'`                     |
| **`listenerFunc`** | `(event: DeviceDisconnectedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('deviceScanned', ...)

```
addListener(eventName: 'deviceScanned', listenerFunc: (event: DeviceScannedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during the scan session.

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'deviceScanned'`                     |
| **`listenerFunc`** | `(event: DeviceScannedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### ConnectOptions

| Prop                | Type      | Description                                                                                                                                                            | Default | Since |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`autoConnect`**   | `boolean` | Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). Only available on Android. | `false` | 7.1.0 |
| **`autoReconnect`** | `boolean` | Whether to enable automatic reconnection to the peripheral when the connection is lost. Only available on Android and iOS (17.0+).                                     | `false` | 7.6.0 |
| **`deviceId`**      | `string`  | The address of the device to connect to.                                                                                                                               |         | 6.0.0 |
| **`timeout`**       | `number`  | The timeout for the connect operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.                                    | `10000` | 6.0.0 |

#### CreateBondOptions

| Prop           | Type     | Description                                                                                                                             | Default | Since |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deviceId`** | `string` | The address of the device to create a bond with.                                                                                        |         | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the create bond operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `10000` | 6.0.0 |

#### DisconnectOptions

| Prop           | Type     | Description                                                                                                                            | Default | Since |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deviceId`** | `string` | The address of the device to disconnect from.                                                                                          |         | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the disconnect operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### DiscoverServiceOptions

| Prop           | Type     | Description                                                                                                                                   | Default | Since |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deviceId`** | `string` | The address of the device to discover services for.                                                                                           |         | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the discover services operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `20000` | 6.0.0 |

#### GetConnectedDevicesResult

| Prop          | Type       | Description                    | Since |
| ------------- | ---------- | ------------------------------ | ----- |
| **`devices`** | `Device[]` | An array of connected devices. | 6.0.0 |

#### Device

| Prop       | Type     | Description                       | Since |
| ---------- | -------- | --------------------------------- | ----- |
| **`id`**   | `string` | The UUID of the connected device. | 6.0.0 |
| **`name`** | `string` | The name of the connected device. | 6.0.0 |

#### GetServicesResult

| Prop           | Type        | Description                                  | Since |
| -------------- | ----------- | -------------------------------------------- | ----- |
| **`services`** | `Service[]` | An array of services provided by the device. | 6.0.0 |

#### Service

| Prop                  | Type               | Description                         | Since |
| --------------------- | ------------------ | ----------------------------------- | ----- |
| **`id`**              | `string`           | The UUID of the service.            | 6.0.0 |
| **`characteristics`** | `Characteristic[]` | The characteristics of the service. | 6.0.0 |

#### Characteristic

| Prop              | Type                        | Description                                                                                                            | Since |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**          | `string`                    | The UUID of the characteristic.                                                                                        | 6.0.0 |
| **`descriptors`** | `Descriptor[]`              | The descriptors of the characteristic. **Note**: This property is currently ignored when advertising a characteristic. | 6.0.0 |
| **`permissions`** | `CharacteristicPermissions` | The permissions of the characteristic. Only available on Android.                                                      | 7.2.0 |
| **`properties`**  | `CharacteristicProperties`  | The properties of the characteristic.                                                                                  | 6.0.0 |

#### Descriptor

| Prop     | Type     | Description                 | Since |
| -------- | -------- | --------------------------- | ----- |
| **`id`** | `string` | The UUID of the descriptor. | 6.0.0 |

#### CharacteristicPermissions

| Prop                     | Type      | Description                                                                                                      | Since |
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------- | ----- |
| **`read`**               | `boolean` | Whether or not the characteristic can be read.                                                                   | 7.2.0 |
| **`readEncrypted`**      | `boolean` | Whether or not the characteristic can be read with encryption.                                                   | 7.2.0 |
| **`readEncryptedMitm`**  | `boolean` | Whether or not the characteristic can be read with encryption and MITM protection. Only available on Android.    | 7.2.0 |
| **`write`**              | `boolean` | Whether or not the characteristic can be written.                                                                | 7.2.0 |
| **`writeEncrypted`**     | `boolean` | Whether or not the characteristic can be written with encryption.                                                | 7.2.0 |
| **`writeEncryptedMitm`** | `boolean` | Whether or not the characteristic can be written with encryption and MITM protection. Only available on Android. | 7.2.0 |
| **`writeSigned`**        | `boolean` | Whether or not the characteristic can be written signed. Only available on Android.                              | 7.2.0 |
| **`writeSignedMitm`**    | `boolean` | Whether or not the characteristic can be written signed with encryption. Only available on Android.              | 7.2.0 |

#### CharacteristicProperties

| Prop                             | Type      | Description                                                        | Since |
| -------------------------------- | --------- | ------------------------------------------------------------------ | ----- |
| **`broadcast`**                  | `boolean` | Whether or not the characteristic can be broadcast.                | 6.0.0 |
| **`read`**                       | `boolean` | Whether or not the characteristic can be read.                     | 6.0.0 |
| **`writeWithoutResponse`**       | `boolean` | Whether or not the characteristic can be written without response. | 6.0.0 |
| **`write`**                      | `boolean` | Whether or not the characteristic can be written.                  | 6.0.0 |
| **`notify`**                     | `boolean` | Whether or not the characteristic supports notifications.          | 6.0.0 |
| **`indicate`**                   | `boolean` | Whether or not the characteristic supports indications.            | 6.0.0 |
| **`authenticatedSignedWrites`**  | `boolean` | Whether or not the characteristic supports signed writes.          | 6.0.0 |
| **`extendedProperties`**         | `boolean` | Whether or not the characteristic supports extended properties.    | 6.0.0 |
| **`notifyEncryptionRequired`**   | `boolean` | Whether or not the characteristic supports reliable writes.        | 6.0.0 |
| **`indicateEncryptionRequired`** | `boolean` | Whether or not the characteristic supports writable auxiliaries.   | 6.0.0 |

#### GetServicesOptions

| Prop           | Type     | Description                                                                                                                              | Default | Since |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deviceId`** | `string` | The address of the device to get the services for.                                                                                       |         | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the get services operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### InitializeOptions

| Prop                 | Type        | Description                                                                                                                                                                                                                                         | Default                                                             | Since       |
| -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------- |
| **`mode`**           | \`'central' | 'peripheral'\`                                                                                                                                                                                                                                      | The mode of the Bluetooth Low Energy plugin. Only available on iOS. | `'central'` |
| **`showPowerAlert`** | `boolean`   | Whether the system should display a warning dialog to the user if Bluetooth is powered off when the plugin is initialized. If not specified, the default value is `true` in `central` mode and `false` in `peripheral` mode. Only available on iOS. |                                                                     | 8.1.0       |

#### IsAvailableResult

| Prop              | Type      | Description                                                     | Since |
| ----------------- | --------- | --------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not Bluetooth Low Energy is available on the device. | 7.3.0 |

#### IsBondedResult

| Prop         | Type      | Description                          | Since |
| ------------ | --------- | ------------------------------------ | ----- |
| **`bonded`** | `boolean` | Whether or not the device is bonded. | 6.0.0 |

#### IsBondedOptions

| Prop           | Type     | Description                                                                                                                           | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`deviceId`** | `string` | The address of the device to check if it is bonded.                                                                                   | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the is bonded operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | 6.0.0 |

#### IsEnabledResult

| Prop          | Type      | Description                          | Since |
| ------------- | --------- | ------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether or not Bluetooth is enabled. | 6.0.0 |

#### IsExtendedAdvertisingAvailableResult

| Prop                           | Type      | Description                                                                                    | Since |
| ------------------------------ | --------- | ---------------------------------------------------------------------------------------------- | ----- |
| **`isAvailable`**              | `boolean` | Whether extended advertising is available on the device.                                       | 8.2.0 |
| **`maxAdvertisingDataLength`** | `number`  | Maximum advertising data length in bytes. This is only available when `isAvailable` is `true`. | 8.2.0 |

#### IsLocationEnabledResult

| Prop          | Type      | Description                                   | Since |
| ------------- | --------- | --------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether or not location services are enabled. | 7.7.0 |

#### ReadCharacteristicResult

| Prop        | Type       | Description                            | Since |
| ----------- | ---------- | -------------------------------------- | ----- |
| **`value`** | `number[]` | The value bytes of the characteristic. | 6.0.0 |

#### ReadCharacteristicOptions

| Prop                   | Type     | Description                                                                                                                      | Default | Since |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`characteristicId`** | `string` | The UUID of the characteristic to read.                                                                                          |         | 6.0.0 |
| **`deviceId`**         | `string` | The address of the device to read the characteristic from.                                                                       |         | 6.0.0 |
| **`serviceId`**        | `string` | The UUID of the service to read the characteristic from.                                                                         |         | 6.0.0 |
| **`timeout`**          | `number` | The timeout for the read operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### ReadDescriptorResult

| Prop        | Type       | Description                        | Since |
| ----------- | ---------- | ---------------------------------- | ----- |
| **`value`** | `number[]` | The value bytes of the descriptor. | 6.0.0 |

#### ReadDescriptorOptions

| Prop                   | Type     | Description                                                                                                                      | Default | Since |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`characteristicId`** | `string` | The UUID of the characteristic that the descriptor belongs to.                                                                   |         | 6.0.0 |
| **`descriptorId`**     | `string` | The UUID of the descriptor to read.                                                                                              |         | 6.0.0 |
| **`deviceId`**         | `string` | The address of the device to read the descriptor from.                                                                           |         | 6.0.0 |
| **`serviceId`**        | `string` | The UUID of the service that the descriptor belongs to.                                                                          |         | 6.0.0 |
| **`timeout`**          | `number` | The timeout for the read operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### ReadRssiResult

| Prop       | Type     | Description     | Since |
| ---------- | -------- | --------------- | ----- |
| **`rssi`** | `number` | The RSSI value. | 6.0.0 |

#### ReadRssiOptions

| Prop           | Type     | Description                                                                                                                           | Default | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`deviceId`** | `string` | The address of the device to read the RSSI for.                                                                                       |         | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the read RSSI operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### RequestConnectionPriorityOptions

| Prop                     | Type                 | Description                                                                                                                                             | Since |
| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`deviceId`**           | `string`             | The address of the device to request the connection priority for.                                                                                       | 6.0.0 |
| **`connectionPriority`** | `ConnectionPriority` | The connection priority to request.                                                                                                                     | 6.0.0 |
| **`timeout`**            | `number`             | The timeout for the request connection priority operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | 6.0.0 |

#### RequestMtuOptions

| Prop           | Type     | Description                                                                                                                             | Since |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`deviceId`** | `string` | The address of the device to request the MTU size for.                                                                                  | 6.0.0 |
| **`mtu`**      | `number` | The mtu size to request.                                                                                                                | 6.0.0 |
| **`timeout`**  | `number` | The timeout for the request MTU operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | 6.0.0 |

#### SetCharacteristicValueOptions

| Prop                   | Type       | Description                                          | Since |
| ---------------------- | ---------- | ---------------------------------------------------- | ----- |
| **`characteristicId`** | `string`   | The UUID of the characteristic to set the value for. | 7.2.0 |
| **`serviceId`**        | `string`   | The UUID of the service to set the value for.        | 7.2.0 |
| **`value`**            | `number[]` | The value bytes to set for the characteristic.       | 7.2.0 |

#### StartAdvertisingOptions

| Prop                   | Type                           | Description                                                                                                                                                                                                                                                                                                | Since |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`manufacturerData`** | `{ [key: number]: number[]; }` | The manufacturer specific data to advertise. Only available on Android.                                                                                                                                                                                                                                    | 7.5.0 |
| **`name`**             | `string`                       | The name of the local device to advertise. On **Android**, for apps targeting `Build.VERSION_CODES.R` or lower, this requires the `BLUETOOTH_ADMIN` permission. For apps targeting `Build.VERSION_CODES.S` or higher, this requires the `BLUETOOTH_CONNECT` permission. Only available on Android and iOS. | 7.2.0 |
| **`serviceData`**      | `{ [key: string]: number[]; }` | [Service](#service) data to advertise (UUID -> byte array). Only available on Android and only when `settings.legacyMode` is `false`.                                                                                                                                                                      | 8.2.0 |
| **`services`**         | `Service[]`                    | The services to advertise.                                                                                                                                                                                                                                                                                 | 7.2.0 |
| **`settings`**         | `AdvertisingSettings`          | Extended advertising settings (BLE 5.0+). Only available on Android.                                                                                                                                                                                                                                       | 8.2.0 |

#### AdvertisingSettings

| Prop               | Type                      | Description                                                                                                                                                                                                                                                                    | Default                           | Since |
| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ----- |
| **`legacyMode`**   | `boolean`                 | Whether to use legacy advertising mode (BLE 4.x compatible). When `true`, uses legacy advertising which is compatible with all BLE devices but limited to ~27-31 bytes of advertising data. When `false`, uses extended advertising (BLE 5.0+) which supports larger payloads. | `true`                            | 8.2.0 |
| **`connectable`**  | `boolean`                 | Whether the advertisement is connectable.                                                                                                                                                                                                                                      | `true`                            | 8.2.0 |
| **`scannable`**    | `boolean`                 | Whether the advertisement is scannable. Only applies when `legacyMode` is `false`.                                                                                                                                                                                             | `false`                           | 8.2.0 |
| **`interval`**     | `AdvertisingInterval`     | Advertising interval.                                                                                                                                                                                                                                                          | `AdvertisingInterval.LOW_LATENCY` | 8.2.0 |
| **`txPowerLevel`** | `AdvertisingTxPowerLevel` | TX power level.                                                                                                                                                                                                                                                                | `AdvertisingTxPowerLevel.HIGH`    | 8.2.0 |
| **`primaryPhy`**   | `AdvertisingPhy`          | Primary PHY for advertising. Only applies when `legacyMode` is `false`.                                                                                                                                                                                                        | `AdvertisingPhy.PHY_LE_1M`        | 8.2.0 |
| **`secondaryPhy`** | `AdvertisingPhy`          | Secondary PHY for advertising. Only applies when `legacyMode` is `false`.                                                                                                                                                                                                      | `AdvertisingPhy.PHY_LE_1M`        | 8.2.0 |

#### StartCharacteristicNotificationsOptions

| Prop                   | Type     | Description                                                                                                                                     | Default | Since |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`characteristicId`** | `string` | The UUID of the characteristic to start notifications for.                                                                                      |         | 6.0.0 |
| **`deviceId`**         | `string` | The address of the device to start notifications for.                                                                                           |         | 6.0.0 |
| **`serviceId`**        | `string` | The UUID of the service to start notifications for.                                                                                             |         | 6.0.0 |
| **`timeout`**          | `number` | The timeout for the start notifications operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### StartForegroundServiceOptions

| Prop            | Type     | Description                                                                                                                                                                                                     | Default                                                                   | Since |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----- |
| **`body`**      | `string` | The body of the notification, shown below the title.                                                                                                                                                            | `"App is running in the background to keep Bluetooth connections alive."` | 6.0.0 |
| **`id`**        | `number` | The notification identifier.                                                                                                                                                                                    | `105`                                                                     | 6.0.0 |
| **`smallIcon`** | `string` | The status bar icon for the notification. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. |                                                                           | 6.0.0 |
| **`title`**     | `string` | The title of the notification.                                                                                                                                                                                  | `"Bluetooth Low Energy"`                                                  | 6.0.0 |

#### StartScanOptions

| Prop                  | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Default                        | Since |
| --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----- |
| **`allowDuplicates`** | `boolean`  | Whether to emit the `deviceScanned` event for every advertisement packet received, instead of only the first advertisement of each device. This is required to receive manufacturer data or service data that is spread across multiple advertisement packets (e.g. when the value is delivered in the scan response packet on iOS). On iOS, this maps to `CBCentralManagerScanOptionAllowDuplicatesKey` and is only honored while the app is in the foreground. | `false`                        | 8.2.0 |
| **`extended`**        | `boolean`  | Whether to use extended advertising scanning (BLE 5.0+) to also discover devices that use extended advertising. When enabled, both legacy and extended advertisements are reported. On **iOS**, extended advertisements are received automatically during a normal scan, so this option is not needed and has no effect. Only available on Android.                                                                                                              | `false`                        | 8.2.0 |
| **`phy`**             | `ScanPhy`  | The PHY to use for scanning. Only applies when `extended` is `true`. Only available on Android.                                                                                                                                                                                                                                                                                                                                                                  | `ScanPhy.PHY_LE_ALL_SUPPORTED` | 8.2.0 |
| **`serviceIds`**      | `string[]` | Find devices with services that match any of the provided UUIDs. Only available on iOS.                                                                                                                                                                                                                                                                                                                                                                          |                                | 6.0.0 |

#### StopCharacteristicNotificationsOptions

| Prop                   | Type     | Description                                                                                                                                    | Default | Since |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`characteristicId`** | `string` | The UUID of the characteristic to stop notifications for.                                                                                      |         | 6.0.0 |
| **`deviceId`**         | `string` | The address of the device to stop notifications for.                                                                                           |         | 6.0.0 |
| **`serviceId`**        | `string` | The UUID of the service to stop notifications for.                                                                                             |         | 6.0.0 |
| **`timeout`**          | `number` | The timeout for the stop notifications operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |

#### WriteCharacteristicOptions

| Prop                   | Type        | Description                                                                                                                       | Default                      | Since       |
| ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- |
| **`characteristicId`** | `string`    | The UUID of the characteristic to write.                                                                                          |                              | 6.0.0       |
| **`deviceId`**         | `string`    | The address of the device to write the characteristic to.                                                                         |                              | 6.0.0       |
| **`serviceId`**        | `string`    | The UUID of the service to write the characteristic to.                                                                           |                              | 6.0.0       |
| **`timeout`**          | `number`    | The timeout for the write operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`                       | 6.0.0       |
| **`type`**             | \`'default' | 'withoutResponse'\`                                                                                                               | The type of write operation. | `'default'` |
| **`value`**            | `number[]`  | The value bytes to write to the characteristic.                                                                                   |                              | 6.0.0       |

#### WriteDescriptorOptions

| Prop                   | Type       | Description                                                                                                                       | Default | Since |
| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`characteristicId`** | `string`   | The UUID of the characteristic that the descriptor belongs to.                                                                    |         | 6.0.0 |
| **`descriptorId`**     | `string`   | The UUID of the descriptor.                                                                                                       |         | 6.0.0 |
| **`deviceId`**         | `string`   | The address of the device that the descriptor belongs to.                                                                         |         | 6.0.0 |
| **`serviceId`**        | `string`   | The UUID of the service that the descriptor belongs to.                                                                           |         | 6.0.0 |
| **`timeout`**          | `number`   | The timeout for the write operation in milliseconds. If the operation takes longer than this value, the promise will be rejected. | `5000`  | 6.0.0 |
| **`value`**            | `number[]` | The value bytes of the descriptor.                                                                                                |         | 6.0.0 |

#### PermissionStatus

| Prop                   | Type              | Description                                                                 | Since |
| ---------------------- | ----------------- | --------------------------------------------------------------------------- | ----- |
| **`bluetooth`**        | `PermissionState` | Permission state for using bluetooth. Only available on iOS.                | 6.0.0 |
| **`bluetoothConnect`** | `PermissionState` | Permission state for connecting to a BLE device. Only available on Android. | 6.0.0 |
| **`bluetoothScan`**    | `PermissionState` | Permission state for scanning for BLE devices. Only available on Android.   | 6.0.0 |
| **`location`**         | `PermissionState` | Permission state for using location services. Only available on Android.    | 6.0.0 |
| **`notifications`**    | `PermissionState` | Permission state for using notifications. Only available on Android.        | 6.0.0 |

#### BluetoothLowEnergyPluginPermission

| Prop              | Type                                 | Description                 | Default                                                                                             |
| ----------------- | ------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------- |
| **`permissions`** | `BluetoothLowEnergyPermissionType[]` | The permissions to request. | `['bluetooth', 'bluetoothAdmin', 'bluetoothConnect', 'bluetoothScan', 'location', 'notifications']` |

#### PluginListenerHandle

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

#### CharacteristicChangedEvent

| Prop                   | Type       | Description                                    | Since |
| ---------------------- | ---------- | ---------------------------------------------- | ----- |
| **`characteristicId`** | `string`   | The UUID of the characteristic.                | 6.0.0 |
| **`deviceId`**         | `string`   | The address of the device.                     | 6.0.0 |
| **`serviceId`**        | `string`   | The UUID of the service.                       | 6.0.0 |
| **`value`**            | `number[]` | The changed value bytes of the characteristic. | 6.0.0 |

#### CharacteristicWriteRequestEvent

| Prop                   | Type       | Description                                     | Since |
| ---------------------- | ---------- | ----------------------------------------------- | ----- |
| **`characteristicId`** | `string`   | The UUID of the characteristic.                 | 7.2.0 |
| **`serviceId`**        | `string`   | The address of the device.                      | 7.2.0 |
| **`value`**            | `number[]` | The value bytes to write to the characteristic. | 7.2.0 |

#### DeviceConnectedEvent

| Prop           | Type     | Description                          | Since |
| -------------- | -------- | ------------------------------------ | ----- |
| **`deviceId`** | `string` | The address of the connected device. | 7.1.0 |
| **`name`**     | `string` | The name of the connected device.    | 7.1.0 |

#### DeviceDisconnectedEvent

| Prop           | Type     | Description                             | Since |
| -------------- | -------- | --------------------------------------- | ----- |
| **`deviceId`** | `string` | The address of the disconnected device. | 6.0.0 |
| **`name`**     | `string` | The name of the disconnected device.    | 6.0.0 |

#### DeviceScannedEvent

| Prop                   | Type                            | Description                                                                                                                                                    | Since |
| ---------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**               | `string`                        | The address of the scanned device.                                                                                                                             | 6.0.0 |
| **`localName`**        | `string`                        | The local name of the scanned device from the advertisement data. In contrast to `name`, this always reflects the value from the current advertisement packet. | 8.2.0 |
| **`manufacturerData`** | `{ [key: number]: number[]; }`  | The manufacturer specific data from the advertisement data. The key is the 16-bit company identifier and the value is the payload bytes.                       | 8.2.0 |
| **`name`**             | `string`                        | The name of the scanned device. On iOS, this returns the cached GAP name and may differ from `localName` after a previous connection to the device.            | 6.0.0 |
| **`rawAdvertisement`** | `number[]`                      | The raw bytes of the advertisement data. Only available on Android.                                                                                            | 8.2.0 |
| **`rssi`**             | `number`                        | The RSSI value of the scanned device.                                                                                                                          | 6.0.0 |
| **`serviceData`**      | `{ [uuid: string]: number[]; }` | The service data from the advertisement data. The key is the service UUID and the value is the payload bytes.                                                  | 8.2.0 |
| **`serviceUuids`**     | `string[]`                      | The UUIDs of the services advertised by the device.                                                                                                            | 8.2.0 |
| **`txPower`**          | `number`                        | The transmit power of the scanned device in dBm.                                                                                                               | 8.2.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### BluetoothLowEnergyPermissionType

`'bluetooth' | 'bluetoothAdmin' | 'bluetoothAdvertise' | 'bluetoothConnect' | 'bluetoothScan' | 'location' | 'notifications'`

### Enums

#### ConnectionPriority

| Members            | Value | Description                          | Since |
| ------------------ | ----- | ------------------------------------ | ----- |
| **`BALANCED`**     | `0`   | Balanced connection priority.        | 6.0.0 |
| **`HIGH`**         | `1`   | High connection priority.            | 6.0.0 |
| **`LOW_POWER`**    | `2`   | Low power connection priority.       | 6.0.0 |
| **`PRIORITY_DCK`** | `3`   | Digital Car Key connection priority. | 6.0.0 |

#### AdvertisingInterval

| Members           | Value           | Description                                | Since |
| ----------------- | --------------- | ------------------------------------------ | ----- |
| **`LOW_LATENCY`** | `'LOW_LATENCY'` | Low latency advertising interval (~100ms). | 8.2.0 |
| **`BALANCED`**    | `'BALANCED'`    | Balanced advertising interval (~250ms).    | 8.2.0 |
| **`LOW_POWER`**   | `'LOW_POWER'`   | Low power advertising interval (~1000ms).  | 8.2.0 |

#### AdvertisingTxPowerLevel

| Members         | Value         | Description               | Since |
| --------------- | ------------- | ------------------------- | ----- |
| **`ULTRA_LOW`** | `'ULTRA_LOW'` | Ultra-low TX power level. | 8.2.0 |
| **`LOW`**       | `'LOW'`       | Low TX power level.       | 8.2.0 |
| **`MEDIUM`**    | `'MEDIUM'`    | Medium TX power level.    | 8.2.0 |
| **`HIGH`**      | `'HIGH'`      | High TX power level.      | 8.2.0 |

#### AdvertisingPhy

| Members            | Value            | Description                                   | Since |
| ------------------ | ---------------- | --------------------------------------------- | ----- |
| **`PHY_LE_1M`**    | `'PHY_LE_1M'`    | LE 1M PHY (default, compatible with BLE 4.x). | 8.2.0 |
| **`PHY_LE_2M`**    | `'PHY_LE_2M'`    | LE 2M PHY (higher throughput, BLE 5.0+).      | 8.2.0 |
| **`PHY_LE_CODED`** | `'PHY_LE_CODED'` | LE Coded PHY (longer range, BLE 5.0+).        | 8.2.0 |

#### ScanPhy

| Members                    | Value                    | Description                            | Since |
| -------------------------- | ------------------------ | -------------------------------------- | ----- |
| **`PHY_LE_1M`**            | `'PHY_LE_1M'`            | LE 1M PHY (compatible with BLE 4.x).   | 8.2.0 |
| **`PHY_LE_CODED`**         | `'PHY_LE_CODED'`         | LE Coded PHY (longer range, BLE 5.0+). | 8.2.0 |
| **`PHY_LE_ALL_SUPPORTED`** | `'PHY_LE_ALL_SUPPORTED'` | Scan on all supported PHYs (default).  | 8.2.0 |

## Utils

This plugin provides a utility class `BluetoothLowEnergyUtils` that can be used for various Bluetooth Low Energy related operations, for example, converting byte arrays to hexadecimal strings:

```
import { BluetoothLowEnergyUtils } from '@capawesome-team/capacitor-bluetooth-low-energy';

const convertBytesToHex = (bytes: number[]) => {
  return BluetoothLowEnergyUtils.convertBytesToHex({ bytes });
};
```

See [docs/utils/README.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/docs/utils/README.md) for more information.

## Bluetooth 5.0 (BLE 5) support

Several BLE 5 capabilities behave differently across platforms due to operating system constraints. These are platform limitations, not limitations of the plugin.

| Capability                                                                                | Android                                           | iOS                                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------ |
| Extended advertising (large payloads, manufacturer/service data, PHY, interval, TX power) | ✅ Supported                                      | ❌ Not supported (no CoreBluetooth API)    |
| Extended advertisement scanning                                                           | ✅ Supported and configurable (`extended`, `phy`) | ✅ Handled automatically, not configurable |
| Coded PHY (LE Long Range)                                                                 | ✅ Supported                                      | ⚠️ Not reliably supported                  |

## FAQ

### Does the plugin work on the Web?

No, the plugin supports Android and iOS. Web browsers do not provide the required APIs for the full feature set of this plugin, such as the peripheral role or foreground services.

### Which permissions do I need on Android?

The required permissions depend on the features you use: `BLUETOOTH_SCAN` and `ACCESS_FINE_LOCATION` for scanning, `BLUETOOTH_CONNECT` for connecting to paired devices, `BLUETOOTH_ADVERTISE` for advertising as a peripheral, and the foreground service permissions if you want to start a foreground service. On Android 11 and below, the legacy `BLUETOOTH` and `BLUETOOTH_ADMIN` permissions are required instead. See [Installation](#installation) for the complete list and use `checkPermissions()` and `requestPermissions()` at runtime.

### How do I keep the BLE connection alive while the app is in the background?

On Android, start a foreground service using the `startForegroundService(...)` method, which requires the service declaration and foreground service permissions described in the [Installation](#installation) section. On iOS, enable the `Background Modes` capability with `bluetooth-central` in your Xcode project.

### Can my app act as a BLE peripheral?

Yes, the plugin supports the peripheral role in addition to the central role. Use `startAdvertising(...)` to advertise your own services to nearby central devices. Note that `setCharacteristicValue(...)` and the `characteristicWriteRequest` event are only available on Android.

### Can I connect to multiple devices at the same time?

Yes, the plugin supports connections to multiple devices at the same time. Each method that operates on a device takes a `deviceId` parameter, and you can retrieve all currently connected devices using the `getConnectedDevices()` method.

### What is a headless task and when do I need one?

A headless task lets you run your own native code when a specific Bluetooth Low Energy event occurs, for example when a characteristic value changes. For this, you create a Java class named `BluetoothLowEnergyHeadlessTask` in the same package as your `MainActivity` on Android, as described in the [Installation](#installation) section. This is useful if you need to react to events even when the web view is not running.

## Related Plugins

- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions to keep background work running reliably.
- [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Run a foreground service on Android.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information such as connection status and type, and listen for network changes.
- [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/): Read, write, and emulate NFC tags with advanced features like HCE and raw command handling.
- [Wi-Fi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Bluetooth SIG, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `Bluetooth` is a registered trademark of Bluetooth SIG, Inc. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor Calendar Plugin

Capacitor plugin to manage calendars and events on Android and iOS. Create, read, update and delete calendars and events, work with recurring events, present the system event dialogs, and listen for calendar changes.

## Features

The Capacitor Calendar plugin gives your app full access to the calendars and events on the device. Here are some of the key features:

- 📅 **Calendars**: Create, delete and retrieve the calendars on the device, including the default calendar for new events.
- 🗓️ **Events**: Create, read, update and delete events, and query all events in a time range with a single call.
- 🔁 **Recurring Events**: Create recurring events with a readable recurrence rule — and read that rule back, instead of only being able to write it.
- 🎯 **Single Occurrences**: Update or delete a single occurrence of a recurring event, or the occurrence and all future ones.
- 📱 **System Dialogs**: Let the user create or edit an event in the system dialog, prefilled with your event data.
- 🔔 **Change Listener**: Get notified when calendars or events change, including changes made by other apps.
- 🔒 **Granular Permissions**: Separate read and write permissions, including write-only calendar access on iOS 17 and newer.
- ⚠️ **Error Codes**: Every runtime failure rejects with a documented error code, so you can branch on it instead of parsing messages.
- 🌍 **All-Day & Time Zones**: A documented all-day and time zone contract that behaves identically on both platforms — no off-by-one-day surprises.
- 🤝 **Compatibility**: Works hand in hand with the [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/) and [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Calendar plugin is typically used whenever an app needs to read from or write to the calendars on the device, for example:

- **Booking and appointment apps**: Write a confirmed booking straight into the user's calendar, including an alert before the appointment, and update or remove it when the booking changes.
- **Field service and scheduling**: Show the agenda of the device next to your own schedule so that technicians and sales reps see conflicts before they accept a job.
- **Fitness and course apps**: Add recurring training sessions or course dates as a single recurring event, and let the user skip a single session without losing the series.
- **Reminders before appointments**: Attach alerts to an event so that the operating system reminds the user, even when your app is not running.
- **Calendar integrations**: Keep events in sync with your backend and react to changes that the user made in the calendar app.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor Calendar Plugin](https://capawesome.io/blog/announcing-the-capacitor-calendar-plugin/): Create, read, and update events with recurrence rules and a calendarChange listener.
- [How to Manage Recurring Calendar Events in Capacitor](https://capawesome.io/blog/recurring-calendar-events-in-capacitor/): Write a recurrence rule, expand it into occurrences, and update or delete a single occurrence or every later one on Android and iOS.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-calendar` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-calendar
npx cap sync
```

### Android

#### Permissions

This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if you want to read calendars and events, for example with `getCalendars()` or `getEvents(...)`. -->
<uses-permission android:name="android.permission.READ_CALENDAR" />
<!-- Required if you want to create, update or delete calendars and events, for example with `createEvent(...)`. -->
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
```

Only declare the permissions that your app actually needs. Keep in mind that `createEvent(...)`, `updateEventById(...)` and `deleteEventById(...)` require the `READ_CALENDAR` permission in addition to the `WRITE_CALENDAR` permission, because they have to look up the calendar or event first. Only `createCalendar(...)` and `deleteCalendarById(...)` work with the `WRITE_CALENDAR` permission alone.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the following keys to the `ios/App/App/Info.plist` file, which tell the user why your app needs access to the calendars:

```
<!-- Required on iOS 17 and newer if your app reads or modifies calendars or events. -->
<key>NSCalendarsFullAccessUsageDescription</key>
<string>The app needs access to your calendars to display and manage your events.</string>
<!-- Required on iOS 17 and newer if your app only requests the `writeCalendar` permission. -->
<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>The app needs access to your calendars to add events for your bookings.</string>
<!-- Required on iOS 16 and older. -->
<key>NSCalendarsUsageDescription</key>
<string>The app needs access to your calendars to display and manage your events.</string>
```

Which keys you need depends on the access that your app requests:

- `NSCalendarsFullAccessUsageDescription` is required on **iOS 17 and newer** whenever the `readCalendar` permission is requested and by every method that reads or modifies calendars or events. Modifying requires full access as well, because the plugin has to look up the calendar or event first.
- `NSCalendarsWriteOnlyAccessUsageDescription` is only required on **iOS 17 and newer** if `requestPermissions(...)` is called with only the `writeCalendar` permission. Write-only access lets your app add events without seeing the events of the user, but is not sufficient for the methods of this plugin.
- `NSCalendarsUsageDescription` is required on **iOS 16 and older**, which does not distinguish between read and write access.

If a required key is missing, `requestPermissions(...)` rejects with a clear error message.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to request permissions, work with calendars and events, create and modify recurring events, present the system event dialogs, and listen for calendar changes.

### Request permissions

Request read and write access to the calendars of the device. Pass the `permissions` option to request only a subset. On iOS 17 and newer, requesting only the `writeCalendar` permission requests write-only access, which does not give your app access to the existing events of the user. Methods such as `createEvent(...)` request full access when they are called, because they have to look up the calendar or event first:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const requestPermissions = async () => {
  const { readCalendar, writeCalendar } = await Calendar.requestPermissions();
  return readCalendar === 'granted' && writeCalendar === 'granted';
};

const requestWriteOnlyPermission = async () => {
  const { writeCalendar } = await Calendar.requestPermissions({
    permissions: ['writeCalendar'],
  });
  return writeCalendar === 'granted';
};
```

### Get the calendars

Retrieve all calendars on the device with `getCalendars()`, or only the calendar that the system uses for new events with `getDefaultCalendar()`. Use the `writable` property to filter out calendars that your app cannot write to, for example subscribed holiday calendars:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const getWritableCalendars = async () => {
  const { calendars } = await Calendar.getCalendars();
  return calendars.filter(calendar => calendar.writable);
};

const getDefaultCalendar = async () => {
  const { calendar } = await Calendar.getDefaultCalendar();
  return calendar;
};
```

### Create an event

Create an event with `createEvent(...)`. Only `title` and `startDate` are required. If no `calendarId` is provided, the event is created in the default calendar. The `alerts` are offsets in minutes before the start of the event:

```
import { Calendar, EventAvailability } from '@capawesome-team/capacitor-calendar';

const createEvent = async (calendarId: string) => {
  const startDate = new Date('2026-09-01T10:00:00').getTime();
  const { id } = await Calendar.createEvent({
    event: {
      calendarId,
      title: 'Dentist appointment',
      startDate,
      endDate: startDate + 60 * 60 * 1000,
      location: 'Main Street 1, Springfield',
      description: 'Bring the insurance card.',
      availability: EventAvailability.Busy,
      alerts: [60, 15],
    },
  });
  return id;
};
```

### Create a recurring event

Add a `recurrence` rule to create a recurring event. The following example creates an event that repeats every week on Mondays and Wednesdays for ten occurrences:

```
import {
  Calendar,
  RecurrenceFrequency,
  Weekday,
} from '@capawesome-team/capacitor-calendar';

const createRecurringEvent = async () => {
  const { id } = await Calendar.createEvent({
    event: {
      title: 'Team stand-up',
      startDate: new Date('2026-09-01T09:00:00').getTime(),
      recurrence: {
        frequency: RecurrenceFrequency.Weekly,
        interval: 1,
        count: 10,
        daysOfWeek: [Weekday.Monday, Weekday.Wednesday],
      },
    },
  });
  return id;
};
```

### Get the events in a range

Query all events that overlap a time range with `getEvents(...)`. Recurring events are expanded, so each occurrence is returned as a separate entry with its own `startDate`. Pass a `calendarId` to restrict the query to a single calendar:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const getEventsOfNextWeek = async () => {
  const from = Date.now();
  const to = from + 7 * 24 * 60 * 60 * 1000;
  const { events } = await Calendar.getEvents({ from, to });
  return events;
};
```

A single event can be retrieved by its identifier with `getEventById(...)`, which resolves with `null` if the event does not exist:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const getEventById = async (id: string) => {
  const { event } = await Calendar.getEventById({ id });
  return event;
};
```

### Update an event

Update an event with `updateEventById(...)`. Only the properties that you pass are changed, all others keep their current values. Setting a property to `null` (or an array property to `[]`) removes it from the event:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const rescheduleEvent = async (id: string, startDate: number) => {
  await Calendar.updateEventById({
    id,
    event: {
      startDate,
      endDate: startDate + 30 * 60 * 1000,
    },
  });
};

const clearEventDetails = async (id: string) => {
  await Calendar.updateEventById({
    id,
    event: {
      location: null,
      description: null,
      alerts: [],
    },
  });
};
```

### Delete a single occurrence

Pass the `instanceStartDate` of an occurrence, as returned by `getEvents(...)`, to apply an operation to a single occurrence of a recurring event instead of the whole series. The `span` option controls whether the operation affects only that occurrence or the occurrence and all future ones:

```
import { Calendar, EventSpan } from '@capawesome-team/capacitor-calendar';

const deleteOccurrence = async (id: string, instanceStartDate: number) => {
  await Calendar.deleteEventById({
    id,
    instanceStartDate,
    span: EventSpan.ThisEvent,
  });
};

const deleteAllFutureOccurrences = async (
  id: string,
  instanceStartDate: number,
) => {
  await Calendar.deleteEventById({
    id,
    instanceStartDate,
    span: EventSpan.ThisAndFutureEvents,
  });
};
```

Without `instanceStartDate`, the entire recurring event is deleted.

### Display the system event dialog

Let the user create an event in the system dialog with `displayCreateEvent(...)`, optionally prefilled with your event data. On iOS, the identifier of the created event is returned if the user saved the event:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const displayCreateEvent = async () => {
  const { id } = await Calendar.displayCreateEvent({
    event: {
      title: 'Lunch with Jane',
      startDate: new Date('2026-09-01T12:00:00').getTime(),
      location: 'Main Street 1, Springfield',
    },
  });
  return id;
};
```

Use `displayUpdateEventById(...)` to let the user edit an existing event. On iOS, the `action` describes what the user did in the dialog:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const displayUpdateEventById = async (id: string) => {
  const { action } = await Calendar.displayUpdateEventById({ id });
  return action;
};
```

The system dialogs on Android do not report a result back to the app, so `id` and `action` are only available on iOS. On Android, only the event properties that are supported by the system intent are prefilled, and the remaining properties are silently ignored.

### Listen for calendar changes

Register a listener for the `calendarChange` event to reload your data whenever calendars or events change, including changes that were made in the calendar app or by other apps. The event carries no payload, because the operating systems do not report which entities changed:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const addCalendarChangeListener = async () => {
  return Calendar.addListener('calendarChange', () => {
    console.log('The calendars or events on the device have changed.');
  });
};

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

### Open the calendar app and the app settings

Open the calendar app of the device at a specific date with `openCalendar(...)`, for example after an event was created. Use `openSettings()` to send the user to the settings of your app so that a previously denied permission can be granted:

```
import { Calendar } from '@capawesome-team/capacitor-calendar';

const openCalendar = async (date: number) => {
  await Calendar.openCalendar({ date });
};

const openSettings = async () => {
  await Calendar.openSettings();
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`createCalendar(...)`](#createcalendar)
- [`createEvent(...)`](#createevent)
- [`deleteCalendarById(...)`](#deletecalendarbyid)
- [`deleteEventById(...)`](#deleteeventbyid)
- [`displayCreateEvent(...)`](#displaycreateevent)
- [`displayUpdateEventById(...)`](#displayupdateeventbyid)
- [`getCalendars()`](#getcalendars)
- [`getDefaultCalendar()`](#getdefaultcalendar)
- [`getEventById(...)`](#geteventbyid)
- [`getEvents(...)`](#getevents)
- [`openCalendar(...)`](#opencalendar)
- [`openSettings()`](#opensettings)
- [`requestPermissions(...)`](#requestpermissions)
- [`updateEventById(...)`](#updateeventbyid)
- [`addListener('calendarChange', ...)`](#addlistenercalendarchange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions to access the device calendar.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### createCalendar(...)

```
createCalendar(options: CreateCalendarOptions) => Promise<CreateCalendarResult>
```

Create a new calendar on the device.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `CreateCalendarOptions` |

**Returns:** `Promise<CreateCalendarResult>`

**Since:** 0.0.1

______________________________________________________________________

### createEvent(...)

```
createEvent(options: CreateEventOptions) => Promise<CreateEventResult>
```

Create a new event in a calendar.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `CreateEventOptions` |

**Returns:** `Promise<CreateEventResult>`

**Since:** 0.0.1

______________________________________________________________________

### deleteCalendarById(...)

```
deleteCalendarById(options: DeleteCalendarByIdOptions) => Promise<void>
```

Delete a calendar from the device.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `DeleteCalendarByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### deleteEventById(...)

```
deleteEventById(options: DeleteEventByIdOptions) => Promise<void>
```

Delete an event from the device.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `DeleteEventByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### displayCreateEvent(...)

```
displayCreateEvent(options?: DisplayCreateEventOptions | undefined) => Promise<DisplayCreateEventResult>
```

Display the system user interface to create a new event.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `DisplayCreateEventOptions` |

**Returns:** `Promise<DisplayCreateEventResult>`

**Since:** 0.0.1

______________________________________________________________________

### displayUpdateEventById(...)

```
displayUpdateEventById(options: DisplayUpdateEventByIdOptions) => Promise<DisplayUpdateEventByIdResult>
```

Display the system user interface to update an existing event.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `DisplayUpdateEventByIdOptions` |

**Returns:** `Promise<DisplayUpdateEventByIdResult>`

**Since:** 0.0.1

______________________________________________________________________

### getCalendars()

```
getCalendars() => Promise<GetCalendarsResult>
```

Get all calendars on the device.

Only available on Android and iOS.

**Returns:** `Promise<GetCalendarsResult>`

**Since:** 0.0.1

______________________________________________________________________

### getDefaultCalendar()

```
getDefaultCalendar() => Promise<GetDefaultCalendarResult>
```

Get the default calendar for new events.

Only available on Android and iOS.

**Returns:** `Promise<GetDefaultCalendarResult>`

**Since:** 0.0.1

______________________________________________________________________

### getEventById(...)

```
getEventById(options: GetEventByIdOptions) => Promise<GetEventByIdResult>
```

Get a single event by its identifier.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GetEventByIdOptions` |

**Returns:** `Promise<GetEventByIdResult>`

**Since:** 0.0.1

______________________________________________________________________

### getEvents(...)

```
getEvents(options: GetEventsOptions) => Promise<GetEventsResult>
```

Get the events in a given time range.

Returns all events that overlap the time range, including single occurrences of recurring events.

Rejects with the error code `CALENDAR_NOT_FOUND` if a `calendarId` is provided but no calendar with that identifier exists.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GetEventsOptions` |

**Returns:** `Promise<GetEventsResult>`

**Since:** 0.0.1

______________________________________________________________________

### openCalendar(...)

```
openCalendar(options?: OpenCalendarOptions | undefined) => Promise<void>
```

Open the calendar app of the device.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `OpenCalendarOptions` |

**Since:** 0.0.1

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the settings of the app so that the user can grant or revoke permissions.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions to access the device calendar.

On iOS 17+, requesting only the `writeCalendar` permission requests write-only access. Requesting the `readCalendar` permission requests full access.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### updateEventById(...)

```
updateEventById(options: UpdateEventByIdOptions) => Promise<void>
```

Update an existing event.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `UpdateEventByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('calendarChange', ...)

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

Called when calendars or events are created, updated or deleted, including by other apps.

Only available on Android and iOS.

| Param              | Type               |
| ------------------ | ------------------ |
| **`eventName`**    | `'calendarChange'` |
| **`listenerFunc`** | `() => void`       |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop                | Type              | Description                                                                                                                  | Since |
| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`readCalendar`**  | `PermissionState` | The permission state for reading calendar data. On iOS, this is `prompt` as long as only write-only access has been granted. | 0.0.1 |
| **`writeCalendar`** | `PermissionState` | The permission state for writing calendar data.                                                                              | 0.0.1 |

#### CreateCalendarResult

| Prop     | Type     | Description                             | Since |
| -------- | -------- | --------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the created calendar. | 0.0.1 |

#### CreateCalendarOptions

| Prop        | Type     | Description                                                        | Since |
| ----------- | -------- | ------------------------------------------------------------------ | ----- |
| **`color`** | `string` | The color of the calendar as a hex string in the format `#RRGGBB`. | 0.0.1 |
| **`title`** | `string` | The title of the calendar.                                         | 0.0.1 |

#### CreateEventResult

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The identifier of the created event. | 0.0.1 |

#### CreateEventOptions

| Prop        | Type         | Description          | Since |
| ----------- | ------------ | -------------------- | ----- |
| **`event`** | `EventInput` | The event to create. | 0.0.1 |

#### EventInput

| Prop               | Type                | Description                                                                                                                                                                                                                                                                     | Default                                   | Since |
| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----- |
| **`alerts`**       | `number[]`          | The alerts of the event as offsets in minutes before the start of the event. Negative values represent minutes after the start.                                                                                                                                                 |                                           | 0.0.1 |
| **`allDay`**       | `boolean`           | Whether the event is an all-day event. For all-day events, `startDate` and `endDate` are interpreted as midnight UTC of the respective calendar day.                                                                                                                            | `false`                                   | 0.0.1 |
| **`availability`** | `EventAvailability` | The availability of the event.                                                                                                                                                                                                                                                  |                                           | 0.0.1 |
| **`calendarId`**   | `string`            | The identifier of the calendar in which the event is created.                                                                                                                                                                                                                   | `The identifier of the default calendar.` | 0.0.1 |
| **`description`**  | `string`            | The description of the event.                                                                                                                                                                                                                                                   |                                           | 0.0.1 |
| **`endDate`**      | `number`            | The end date of the event as a timestamp in milliseconds. If not provided, the event ends one hour after `startDate` (all-day events: on the same day as `startDate`). For all-day events, the end date is exclusive (midnight UTC of the day after the last day of the event). |                                           | 0.0.1 |
| **`location`**     | `string`            | The location of the event.                                                                                                                                                                                                                                                      |                                           | 0.0.1 |
| **`recurrence`**   | `RecurrenceRule`    | The recurrence rule of the event.                                                                                                                                                                                                                                               |                                           | 0.0.1 |
| **`startDate`**    | `number`            | The start date of the event as a timestamp in milliseconds.                                                                                                                                                                                                                     |                                           | 0.0.1 |
| **`timezone`**     | `string`            | The time zone of the event as an IANA time zone identifier.                                                                                                                                                                                                                     | `The default time zone of the device.`    | 0.0.1 |
| **`title`**        | `string`            | The title of the event.                                                                                                                                                                                                                                                         |                                           | 0.0.1 |

#### RecurrenceRule

| Prop             | Type                  | Description                                                                                                                                                    | Default | Since |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`count`**      | `number`              | The number of occurrences after which the recurrence ends. Takes precedence over `until`.                                                                      |         | 0.0.1 |
| **`daysOfWeek`** | `Weekday[]`           | The days of the week on which the event recurs.                                                                                                                |         | 0.0.1 |
| **`frequency`**  | `RecurrenceFrequency` | The frequency of the recurrence.                                                                                                                               |         | 0.0.1 |
| **`interval`**   | `number`              | The interval between occurrences of the recurrence. For example, an interval of `2` with a `Weekly` frequency results in an event that recurs every two weeks. | `1`     | 0.0.1 |
| **`until`**      | `number`              | The date on which the recurrence ends as a timestamp in milliseconds.                                                                                          |         | 0.0.1 |

#### DeleteCalendarByIdOptions

| Prop     | Type     | Description                               | Since |
| -------- | -------- | ----------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the calendar to delete. | 0.0.1 |

#### DeleteEventByIdOptions

| Prop                    | Type        | Description                                                                                                                                                                                                                                                                                                              | Default               | Since |
| ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ----- |
| **`id`**                | `string`    | The identifier of the event to delete.                                                                                                                                                                                                                                                                                   |                       | 0.0.1 |
| **`instanceStartDate`** | `number`    | The start date of a single occurrence of a recurring event as a timestamp in milliseconds, as returned by `getEvents(...)`. If provided, only the given occurrence (or, depending on `span`, the given and all future occurrences) of the recurring event is deleted. If omitted, the entire recurring event is deleted. |                       | 0.0.1 |
| **`span`**              | `EventSpan` | The span of a recurring event to which the operation is applied. Only applied when `instanceStartDate` is provided.                                                                                                                                                                                                      | `EventSpan.ThisEvent` | 0.0.1 |

#### DisplayCreateEventResult

| Prop     | Type     | Description                                                                                       | Since |
| -------- | -------- | ------------------------------------------------------------------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the created event. Only returned if the event was saved. Only available on iOS. | 0.0.1 |

#### DisplayCreateEventOptions

| Prop        | Type                  | Description                                                                                                                                                                 | Since |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`event`** | `Partial<EventInput>` | The event data with which the dialog is prefilled. On Android, only the properties supported by the system intent are applied. Unsupported properties are silently ignored. | 0.0.1 |

#### DisplayUpdateEventByIdResult

| Prop         | Type              | Description                                                              | Since |
| ------------ | ----------------- | ------------------------------------------------------------------------ | ----- |
| **`action`** | `EventEditAction` | The action that the user performed in the dialog. Only available on iOS. | 0.0.1 |

#### DisplayUpdateEventByIdOptions

| Prop     | Type     | Description                            | Since |
| -------- | -------- | -------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the event to update. | 0.0.1 |

#### GetCalendarsResult

| Prop            | Type         | Description                  | Since |
| --------------- | ------------ | ---------------------------- | ----- |
| **`calendars`** | `Calendar[]` | The calendars on the device. | 0.0.1 |

#### Calendar

| Prop           | Type      | Description                                                        | Since |
| -------------- | --------- | ------------------------------------------------------------------ | ----- |
| **`color`**    | `string`  | The color of the calendar as a hex string in the format `#RRGGBB`. | 0.0.1 |
| **`id`**       | `string`  | The identifier of the calendar.                                    | 0.0.1 |
| **`title`**    | `string`  | The title of the calendar.                                         | 0.0.1 |
| **`writable`** | `boolean` | Whether events can be added, updated, or deleted in this calendar. | 0.0.1 |

#### GetDefaultCalendarResult

| Prop           | Type       | Description | Since                                                                                         |
| -------------- | ---------- | ----------- | --------------------------------------------------------------------------------------------- |
| **`calendar`** | \`Calendar | null\`      | The default calendar for new events. If no default calendar is available, `null` is returned. |

#### GetEventByIdResult

| Prop        | Type            | Description | Since                                                                           |
| ----------- | --------------- | ----------- | ------------------------------------------------------------------------------- |
| **`event`** | \`CalendarEvent | null\`      | The event with the given identifier. If no event was found, `null` is returned. |

#### CalendarEvent

| Prop               | Type                | Description                                                                                                                                                        | Since |
| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`alerts`**       | `number[]`          | The alerts of the event as offsets in minutes before the start of the event. Negative values represent minutes after the start.                                    | 0.0.1 |
| **`allDay`**       | `boolean`           | Whether the event is an all-day event. For all-day events, `startDate` and `endDate` are returned as midnight UTC of the respective calendar day.                  | 0.0.1 |
| **`availability`** | `EventAvailability` | The availability of the event.                                                                                                                                     | 0.0.1 |
| **`calendarId`**   | `string`            | The identifier of the calendar that the event belongs to.                                                                                                          | 0.0.1 |
| **`description`**  | `string`            | The description of the event.                                                                                                                                      | 0.0.1 |
| **`endDate`**      | `number`            | The end date of the event as a timestamp in milliseconds. For all-day events, the end date is exclusive (midnight UTC of the day after the last day of the event). | 0.0.1 |
| **`id`**           | `string`            | The identifier of the event. All occurrences of a recurring event share the same identifier.                                                                       | 0.0.1 |
| **`location`**     | `string`            | The location of the event.                                                                                                                                         | 0.0.1 |
| **`recurrence`**   | `RecurrenceRule`    | The recurrence rule of the event.                                                                                                                                  | 0.0.1 |
| **`startDate`**    | `number`            | The start date of the event as a timestamp in milliseconds.                                                                                                        | 0.0.1 |
| **`status`**       | `EventStatus`       | The confirmation status of the event.                                                                                                                              | 0.0.1 |
| **`timezone`**     | `string`            | The time zone of the event as an IANA time zone identifier.                                                                                                        | 0.0.1 |
| **`title`**        | `string`            | The title of the event.                                                                                                                                            | 0.0.1 |

#### GetEventByIdOptions

| Prop     | Type     | Description                  | Since |
| -------- | -------- | ---------------------------- | ----- |
| **`id`** | `string` | The identifier of the event. | 0.0.1 |

#### GetEventsResult

| Prop         | Type              | Description                         | Since |
| ------------ | ----------------- | ----------------------------------- | ----- |
| **`events`** | `CalendarEvent[]` | The events in the given time range. | 0.0.1 |

#### GetEventsOptions

| Prop             | Type     | Description                                                                                                           | Since |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`calendarId`** | `string` | The identifier of the calendar to get the events from. If not provided, the events of all calendars are returned.     | 0.0.1 |
| **`from`**       | `number` | The start of the time range as a timestamp in milliseconds.                                                           | 0.0.1 |
| **`to`**         | `number` | The end of the time range as a timestamp in milliseconds. On iOS, only the first 100 years after `from` are searched. | 0.0.1 |

#### OpenCalendarOptions

| Prop       | Type     | Description                                                                  | Default             | Since |
| ---------- | -------- | ---------------------------------------------------------------------------- | ------------------- | ----- |
| **`date`** | `number` | The date to which the calendar app is opened as a timestamp in milliseconds. | `The current time.` | 0.0.1 |

#### RequestPermissionsOptions

| Prop              | Type                       | Description                 | Default                             | Since |
| ----------------- | -------------------------- | --------------------------- | ----------------------------------- | ----- |
| **`permissions`** | `CalendarPermissionType[]` | The permissions to request. | `['readCalendar', 'writeCalendar']` | 0.0.1 |

#### UpdateEventByIdOptions

| Prop                    | Type                            | Description                                                                                                                                                                                                                                                                                                                    | Default               | Since |
| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ----- |
| **`event`**             | `Nullable<Partial<EventInput>>` | The updated event data. Missing properties are ignored and keep their existing values. Properties explicitly set to `null` (or empty arrays `[]`) will be removed from the event. Properties that are required for the event structure (`allDay`, `calendarId`, `endDate`, `startDate`, `timezone`) must not be set to `null`. |                       | 0.0.1 |
| **`id`**                | `string`                        | The identifier of the event to update.                                                                                                                                                                                                                                                                                         |                       | 0.0.1 |
| **`instanceStartDate`** | `number`                        | The start date of a single occurrence of a recurring event as a timestamp in milliseconds, as returned by `getEvents(...)`. If provided, only the given occurrence (or, depending on `span`, the given and all future occurrences) of the recurring event is updated. If omitted, the entire recurring event is updated.       |                       | 0.0.1 |
| **`span`**              | `EventSpan`                     | The span of a recurring event to which the operation is applied. Only applied when `instanceStartDate` is provided.                                                                                                                                                                                                            | `EventSpan.ThisEvent` | 0.0.1 |

#### PluginListenerHandle

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

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### EventEditAction

The action that the user performed in a system event dialog.

`'canceled' | 'deleted' | 'saved'`

#### EventStatus

The confirmation status of an event.

`'canceled' | 'confirmed' | 'tentative'`

#### CalendarPermissionType

The permissions to request when calling `requestPermissions(...)`.

`'readCalendar' | 'writeCalendar'`

#### Nullable

`{ [K in keyof T]: T[K] | null }`

### Enums

#### EventAvailability

| Members           | Value           | Description                                                                                 | Since |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------- | ----- |
| **`Busy`**        | `'BUSY'`        | The time of the event is marked as busy.                                                    | 0.0.1 |
| **`Free`**        | `'FREE'`        | The time of the event is marked as free.                                                    | 0.0.1 |
| **`Tentative`**   | `'TENTATIVE'`   | The time of the event is marked as tentative.                                               | 0.0.1 |
| **`Unavailable`** | `'UNAVAILABLE'` | The time of the event is marked as unavailable. On Android, this value is mapped to `Busy`. | 0.0.1 |

#### Weekday

| Members         | Value         | Description                     | Since |
| --------------- | ------------- | ------------------------------- | ----- |
| **`Friday`**    | `'FRIDAY'`    | The event recurs on Fridays.    | 0.0.1 |
| **`Monday`**    | `'MONDAY'`    | The event recurs on Mondays.    | 0.0.1 |
| **`Saturday`**  | `'SATURDAY'`  | The event recurs on Saturdays.  | 0.0.1 |
| **`Sunday`**    | `'SUNDAY'`    | The event recurs on Sundays.    | 0.0.1 |
| **`Thursday`**  | `'THURSDAY'`  | The event recurs on Thursdays.  | 0.0.1 |
| **`Tuesday`**   | `'TUESDAY'`   | The event recurs on Tuesdays.   | 0.0.1 |
| **`Wednesday`** | `'WEDNESDAY'` | The event recurs on Wednesdays. | 0.0.1 |

#### RecurrenceFrequency

| Members       | Value       | Description               | Since |
| ------------- | ----------- | ------------------------- | ----- |
| **`Daily`**   | `'DAILY'`   | The event recurs daily.   | 0.0.1 |
| **`Monthly`** | `'MONTHLY'` | The event recurs monthly. | 0.0.1 |
| **`Weekly`**  | `'WEEKLY'`  | The event recurs weekly.  | 0.0.1 |
| **`Yearly`**  | `'YEARLY'`  | The event recurs yearly.  | 0.0.1 |

#### EventSpan

| Members                   | Value                      | Description                                                                                         | Since |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`ThisAndFutureEvents`** | `'THIS_AND_FUTURE_EVENTS'` | The operation is applied to the given occurrence and all future occurrences of the recurring event. | 0.0.1 |
| **`ThisEvent`**           | `'THIS_EVENT'`             | The operation is applied only to the given occurrence of the recurring event.                       | 0.0.1 |

## Recurring Events

Recurring events are stored as a single event with a recurrence rule, but they are displayed to the user as many occurrences. The plugin makes both views available and keeps them consistent across Android and iOS.

**Occurrence expansion**: `getEvents(...)` expands recurring events into their occurrences. Each occurrence is returned as a separate entry whose `startDate` and `endDate` describe that occurrence, while the `id` and the `recurrence` rule are the same for all occurrences of the same series. `getEventById(...)`, in contrast, always returns the series itself with its original start date.

**Targeting a single occurrence**: `updateEventById(...)` and `deleteEventById(...)` operate on the whole series by default. Pass the `startDate` of an occurrence as `instanceStartDate` to target that occurrence instead, and use `span` to choose the scope:

- `EventSpan.ThisEvent` (default) applies the change to the given occurrence only. The rest of the series remains untouched.
- `EventSpan.ThisAndFutureEvents` applies the change to the given occurrence and all following ones, while past occurrences remain untouched.

**Reading a rule back**: the `recurrence` property of an event is both written and read. A rule that uses parts which are not supported by the plugin — for example a rule created in another app — is read back as the closest supported subset, so `frequency` and `interval` are always correct even if a more exotic part is dropped.

**All-day events and time zones**: an event with `allDay: true` has no time of day. Its `startDate` and `endDate` are therefore interpreted and returned as **midnight UTC** of the respective calendar day on both platforms, independent of the time zone of the device. The `endDate` is **exclusive**: it is midnight UTC of the day after the last day of the event, so a one-day all-day event on `2026-09-01` has `startDate = Date.UTC(2026, 8, 1)` and `endDate = Date.UTC(2026, 8, 2)`. An `endDate` that is missing or not on a midnight boundary is normalized: it is floored to midnight UTC of its day and raised to at least one day after `startDate`, so the event always spans at least one full day. Build these timestamps in UTC, for example with `Date.UTC(2026, 8, 1)`, and format them in UTC as well — using the local time zone instead is what makes an all-day event appear on the wrong day. For events that are not all-day, the `timezone` property defines the time zone in which the event takes place and defaults to the time zone of the device.

## FAQ

### How is this plugin different from other similar plugins?

We focused on correctness instead of a long feature list. Every runtime failure rejects with a documented error code, so your app can react to a missing event or a read-only calendar programmatically. Recurrence rules can be read back, not just written, so a recurring event can round-trip through your app without losing information. Single occurrences of a recurring event can be updated and deleted, including all future occurrences. All-day events and time zones follow one documented contract on both platforms, and behavior that only one platform can provide is documented as such instead of being silently faked. On top of that, the plugin is covered by unit tests, is built from the ground up by the Capawesome Team, and comes with priority support.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/): Read and write device contacts, for example to invite them to an event.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Let the user pick the date and time of an event natively.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/calendar/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/calendar/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/calendar/LICENSE).

# Capacitor Clipboard Plugin

Capacitor plugin to read from and write to the system clipboard.

## Features

- 📋 **Read & Write**: Read from and write to the system clipboard.
- 🖼️ **Images**: Copy and paste real images, not just data URLs as plain text.
- 📝 **Rich Text**: Write HTML content with a plain-text fallback.
- 🔗 **URLs**: Copy URLs as native URL clipboard items.
- 🌐 **Cross-platform**: Works on Android, iOS, and the web.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/) and [Text Interaction](https://capawesome.io/docs/sdks/capacitor/text-interaction/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Clipboard plugin is typically used whenever an app lets users copy or paste content, for example:

- **Copy to clipboard buttons**: Let users copy coupon codes, invite links, or wallet addresses with one tap.
- **Paste support**: Read text, URLs, or images from the clipboard into your app, for example into a form or editor.
- **Sharing images**: Copy a generated image (such as a QR code or chart) so users can paste it into other apps.
- **Rich text workflows**: Copy formatted HTML content with a plain-text fallback for apps that cannot handle HTML.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-clipboard` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-clipboard
npx cap sync
```

### Android

No additional configuration is required for this plugin.

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to write text, HTML, images, and URLs to the clipboard, and how to read its current content.

### Write text to the clipboard

Copy plain text to the system clipboard:

```
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeText = async () => {
  await Clipboard.write({ text: 'Hello World' });
};
```

### Write HTML with a plain-text fallback

Copy HTML content and combine it with `text` to provide a plain-text fallback for apps that cannot handle HTML content:

```
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeHtml = async () => {
  await Clipboard.write({
    html: '<b>Hello World</b>',
    text: 'Hello World',
  });
};
```

### Write an image to the clipboard

Copy a real image (not just a data URL as plain text) by passing a Base64-encoded data URL:

```
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeImage = async () => {
  await Clipboard.write({
    image: 'data:image/png;base64,iVBORw0KGgo...',
  });
};
```

### Write a URL to the clipboard

Copy a URL as a native URL clipboard item:

```
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeUrl = async () => {
  await Clipboard.write({ url: 'https://capawesome.io' });
};
```

### Read the clipboard content

Read the current content of the system clipboard. The result contains the content type (text, HTML, image, or URL) and the value. Note that on Android, reading the clipboard is only possible while the app is in the foreground, and on iOS, a system paste notification is displayed:

```
import { Clipboard } from '@capawesome/capacitor-clipboard';

const read = async () => {
  const { type, value } = await Clipboard.read();
  console.log('Type:', type, 'Value:', value);
};
```

## API

- [`read()`](#read)
- [`write(...)`](#write)
- [Interfaces](#interfaces)
- [Enums](#enums)

### read()

```
read() => Promise<ReadResult>
```

Read the current content of the system clipboard.

On Android, reading the clipboard is only possible while the app is in the foreground.

On iOS, reading the clipboard displays a system paste notification. This is expected behavior and cannot be suppressed.

**Returns:** `Promise<ReadResult>`

**Since:** 0.1.0

______________________________________________________________________

### write(...)

```
write(options: WriteOptions) => Promise<void>
```

Write content to the system clipboard.

Exactly one of `text`, `html`, `image` or `url` must be provided. The `html` property may additionally be combined with `text` to provide a plain-text fallback.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `WriteOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ReadResult

| Prop        | Type                   | Description                                                                                     | Since |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------- | ----- |
| **`type`**  | `ClipboardContentType` | The type of the content that was read from the clipboard.                                       | 0.1.0 |
| **`value`** | `string`               | The content that was read from the clipboard. Images are returned as a Base64-encoded data URL. | 0.1.0 |

#### WriteOptions

| Prop        | Type     | Description                                                                                                                                     | Since |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`html`**  | `string` | The HTML content to write to the clipboard. Combine this with `text` to provide a plain-text fallback for apps that cannot handle HTML content. | 0.1.0 |
| **`image`** | `string` | The image to write to the clipboard as a Base64-encoded data URL.                                                                               | 0.1.0 |
| **`label`** | `string` | The label used to describe the clipboard content. Only available on Android.                                                                    | 0.1.0 |
| **`text`**  | `string` | The plain text to write to the clipboard.                                                                                                       | 0.1.0 |
| **`url`**   | `string` | The URL to write to the clipboard.                                                                                                              | 0.1.0 |

### Enums

#### ClipboardContentType

| Members     | Value     | Description                                                     | Since |
| ----------- | --------- | --------------------------------------------------------------- | ----- |
| **`Html`**  | `'HTML'`  | The content is HTML.                                            | 0.1.0 |
| **`Image`** | `'IMAGE'` | The content is an image, returned as a Base64-encoded data URL. | 0.1.0 |
| **`Text`**  | `'TEXT'`  | The content is plain text.                                      | 0.1.0 |
| **`Url`**   | `'URL'`   | The content is a URL.                                           | 0.1.0 |

## Platform Behavior

### Android

- On Android 10 (API level 29) and later, apps can only read the clipboard while they are in the foreground and have input focus. The `read(...)` method rejects otherwise.
- On Android 12 (API level 31) and later, the system shows a toast message when an app reads the clipboard content that was written by another app. This is expected behavior and cannot be suppressed.

### iOS

- On iOS 14 and later, the system shows a paste notification banner every time the clipboard is read. This is expected behavior and cannot be suppressed.

## Migrating from `@capacitor/clipboard`

This plugin is a drop-in alternative to the official [`@capacitor/clipboard`](https://github.com/ionic-team/capacitor-plugins/tree/main/clipboard) plugin with real image support on Android and HTML support on all platforms. The following differences apply:

| `@capacitor/clipboard`                             | `@capawesome/capacitor-clipboard`                         |
| -------------------------------------------------- | --------------------------------------------------------- |
| `write({ string: 'Hello' })`                       | `write({ text: 'Hello' })`                                |
| `write({ image: dataUrl })` (text-only on Android) | `write({ image: dataUrl })` (real image on all platforms) |
| —                                                  | `write({ html: '<b>Hello</b>', text: 'Hello' })`          |
| `read() → { value, type: 'text/plain' }`           | `read() → { value, type: 'TEXT' }`                        |

## FAQ

### How is this plugin different from other similar plugins?

It supports far more than plain text — copy and paste images, HTML with a plain-text fallback, and native URL items, with reliable real image handling on Android, iOS, and the web. The API is fully typed and actively maintained against the latest OS and framework versions, and it uses only official platform APIs so it stays safe for App Store and Google Play submissions. If you only ever copy plain text, a simpler setup is perfectly fine; if you need rich content and consistent behavior across every platform, this plugin is designed for exactly that.

### Why is a notification shown when my app reads the clipboard?

On iOS 14 and later, the system shows a paste notification banner every time the clipboard is read. On Android 12 (API level 31) and later, the system shows a toast message when an app reads clipboard content that was written by another app. Both are expected platform behavior and cannot be suppressed.

### Why does reading the clipboard fail on Android?

On Android 10 (API level 29) and later, apps can only read the clipboard while they are in the foreground and have input focus. The `read()` method rejects otherwise, so make sure to only call it in response to a user interaction while the app is visible.

### Can I write multiple content types at once?

No, exactly one of `text`, `html`, `image` or `url` must be provided when calling `write(...)`. The only exception is that `html` may additionally be combined with `text` to provide a plain-text fallback for apps that cannot handle HTML content.

### How are images handled by this plugin?

Images are written to the clipboard as real images, not just data URLs as plain text, by passing a Base64-encoded data URL to `write(...)`. When reading, images are also returned as a Base64-encoded data URL. See the [usage examples](#write-an-image-to-the-clipboard) above.

### How is this plugin different from the official `@capacitor/clipboard` plugin?

This plugin is a drop-in alternative to the official `@capacitor/clipboard` plugin with real image support on Android and HTML support on all platforms. Only a few method options differ, see the [migration table](#migrating-from-capacitorclipboard) above.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive content such as text, links, and files from other apps.
- [Text Interaction](https://capawesome.io/docs/sdks/capacitor/text-interaction/): Enable and disable text interaction (selection, magnifier, callout menu) in the app's WebView.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/clipboard/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/clipboard/LICENSE).

# Capacitor Cloudinary Plugin

Unofficial Capacitor plugin for [Cloudinary SDK](https://cloudinary.com/documentation/cloudinary_sdks).[1](#fn:1)

## Features

Capacitor Cloudinary allows you to use the native Cloudinary SDKs to upload files directly from the filesystem without going through the WebView.

- 🔋 Supports Android, iOS and the Web
- 🍕 Chunk upload of large files
- ❌ No more out-of-memory issues
- 📁 Works with the [Capacitor Filesystem](https://capacitorjs.com/docs/apis/filesystem) and [Capacitor File Picker](https://github.com/capawesome-team/capacitor-file-picker)
- 🤝 **Compatibility**: Works alongside the [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugins.

## Use Cases

The Cloudinary plugin is typically used whenever an app needs to exchange media files with Cloudinary, for example:

- **User-generated content**: Upload photos and videos that users select from their device directly to your Cloudinary account.
- **Large video uploads**: Upload large files in chunks via the native Cloudinary SDKs to avoid out-of-memory crashes in the WebView.
- **Profile pictures**: Upload an image with a unique public identifier so it can be referenced and replaced later.
- **Media downloads**: Download images, videos, or raw files from Cloudinary to the device for further processing.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-cloudinary` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-cloudinary
npx cap sync
```

### Android

This API requires the following permission be added to your `AndroidManifest.xml` **before** the `application` tag:

```
<uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
```

You also need to add the following receiver **inside** the `application` tag in your `AndroidManifest.xml`:

```
<receiver android:name="io.capawesome.capacitorjs.plugins.cloudinary.DownloadBroadcastReceiver" android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>
  </intent-filter>
</receiver>
```

#### 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:

- `$cloudinaryAndroidVersion` version of `com.cloudinary:cloudinary-android` (default: `3.1.2`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize the plugin, upload a file to Cloudinary, and download a file from Cloudinary.

### Initialize the plugin

Initialize the plugin with the cloud name of your app, which you can find in the Cloudinary Management Console. This method must be called once before all other methods:

```
import { Cloudinary } from '@capawesome/capacitor-cloudinary';

const initialize = async () => {
  await Cloudinary.initialize({ cloudName: 'my_cloud_name' });
};
```

### Upload a file to Cloudinary

Upload an image, video, or raw file to Cloudinary. On Android and iOS, pass the path of the file to upload; on the Web, pass a `Blob` instead. Note that currently only unsigned uploads are supported, so you need an upload preset:

```
import { Cloudinary, ResourceType } from '@capawesome/capacitor-cloudinary';

const uploadResource = async () => {
  await Cloudinary.uploadResource({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Images/test.png',
    publicId: 'my_public_id',
    resourceType: ResourceType.image,
    uploadPreset: 'my_preset',
  });
};
```

### Download a file from Cloudinary

Download a resource by its URL. On Android and iOS, the result contains the path where the file was stored on the device; on the Web, it contains a `Blob`:

```
import { Cloudinary } from '@capawesome/capacitor-cloudinary';

const downloadResource = async () => {
  const { path } = await Cloudinary.downloadResource({
    url: 'https://res.cloudinary.com/myCloudName/image/upload/v123/123.png',
  });
  return path;
};
```

## API

- [`initialize(...)`](#initialize)
- [`uploadResource(...)`](#uploadresource)
- [`downloadResource(...)`](#downloadresource)
- [Interfaces](#interfaces)
- [Enums](#enums)

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the plugin.

This method must be called once before all other methods.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### uploadResource(...)

```
uploadResource(options: UploadResourceOptions) => Promise<UploadResourceResult>
```

Upload a file to Cloudinary.

**Note**: Currently, only unsigned uploads are supported.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `UploadResourceOptions` |

**Returns:** `Promise<UploadResourceResult>`

**Since:** 0.0.1

______________________________________________________________________

### downloadResource(...)

```
downloadResource(options: DownloadResourceOptions) => Promise<DownloadResourceResult>
```

Download a file from Cloudinary.

On **Android**, the file will be downloaded to the `Downloads` directory. On **iOS**, the file will be downloaded to the temporary directory.

It is recommended to copy the file to a permanent location for further processing after downloading.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `DownloadResourceOptions` |

**Returns:** `Promise<DownloadResourceResult>`

**Since:** 0.0.3

______________________________________________________________________

### Interfaces

#### InitializeOptions

| Prop            | Type     | Description                                                                         | Since |
| --------------- | -------- | ----------------------------------------------------------------------------------- | ----- |
| **`cloudName`** | `string` | The cloud name of your app which you can find in the Cloudinary Management Console. | 0.0.1 |

#### UploadResourceResult

| Prop                   | Type           | Description                                                                              | Since |
| ---------------------- | -------------- | ---------------------------------------------------------------------------------------- | ----- |
| **`assetId`**          | `string`       | The unique asset identifier of the uploaded resource. Only available on Android and Web. | 0.0.1 |
| **`bytes`**            | `number`       | The number of bytes of the uploaded resource.                                            | 0.0.1 |
| **`createdAt`**        | `string`       | The timestamp at which the resource was uploaded.                                        | 0.0.1 |
| **`duration`**         | `number`       | The duration of the uploaded resource in seconds.                                        | 0.1.5 |
| **`format`**           | `string`       | The format of the uploaded resource.                                                     | 0.0.1 |
| **`height`**           | `number`       | The height of the uploaded resource.                                                     | 0.1.4 |
| **`originalFilename`** | `string`       | The original filename of the uploaded resource. Only available on Android and iOS.       | 0.0.1 |
| **`resourceType`**     | `ResourceType` | The resource type of the uploaded resource.                                              | 0.0.1 |
| **`publicId`**         | `string`       | The unique public identifier of the uploaded resource.                                   | 0.0.1 |
| **`url`**              | `string`       | The url of the uploaded resource.                                                        | 0.0.1 |
| **`secureUrl`**        | `string`       | The secure url of the uploaded resource.                                                 | 5.1.0 |
| **`width`**            | `number`       | The width of the uploaded resource.                                                      | 0.1.4 |

#### UploadResourceOptions

| Prop               | Type           | Description                                                        | Since |
| ------------------ | -------------- | ------------------------------------------------------------------ | ----- |
| **`resourceType`** | `ResourceType` | The resource type to upload.                                       | 0.0.1 |
| **`blob`**         | `Blob`         | The file to upload. Only available on Web.                         | 0.0.1 |
| **`uploadPreset`** | `string`       | The selected upload preset.                                        | 0.0.1 |
| **`path`**         | `string`       | The path of the file to upload. Only available on Android and iOS. | 0.0.1 |
| **`publicId`**     | `string`       | Assign a unique public identifier to the resource.                 | 0.0.1 |

#### DownloadResourceResult

| Prop       | Type     | Description                                                                                              | Since |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path of the downloaded resource where it is stored on the device. Only available on Android and iOS. | 0.0.3 |
| **`blob`** | `Blob`   | The downloaded resource as a blob. Only available on Web.                                                | 0.0.1 |

#### DownloadResourceOptions

| Prop      | Type     | Description                          | Since |
| --------- | -------- | ------------------------------------ | ----- |
| **`url`** | `string` | The url of the resource to download. | 0.0.3 |

### Enums

#### ResourceType

| Members     | Value     | Since |
| ----------- | --------- | ----- |
| **`Image`** | `'image'` | 0.0.1 |
| **`Video`** | `'video'` | 0.0.1 |
| **`Raw`**   | `'raw'`   | 0.0.1 |

## Utils

See [docs/utils/README.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/cloudinary/docs/utils/README.md).

## FAQ

### Do I need to call `initialize` before using the plugin?

Yes, the `initialize(...)` method must be called once before all other methods. It only requires the cloud name of your app, which you can find in the Cloudinary Management Console. See the [usage example](#initialize-the-plugin) above.

### Are signed uploads supported?

No, currently only unsigned uploads are supported. This means you need to create an unsigned upload preset in your Cloudinary account and pass its name via the `uploadPreset` option when calling `uploadResource(...)`.

### Where are downloaded files stored?

On Android, the file is downloaded to the `Downloads` directory. On iOS, the file is downloaded to the temporary directory, so it is recommended to copy it to a permanent location for further processing. On the Web, the downloaded resource is returned as a `Blob` instead of a path.

### How do I upload a file on the Web?

On the Web, pass the file as a `Blob` via the `blob` option of `uploadResource(...)`. The `path` option is only available on Android and iOS, where it points to a file on the device's filesystem.

### What do I need to configure on Android?

You need to add the `DOWNLOAD_WITHOUT_NOTIFICATION` permission and the `DownloadBroadcastReceiver` receiver to your `AndroidManifest.xml`, as described in the [Installation](#installation) section. No additional configuration is required on iOS or the Web.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress images before uploading them.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a downloaded file with the default application.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file, image, or video to upload to Cloudinary.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/cloudinary/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/cloudinary/LICENSE).

## Credits

This plugin is based on the [Capacitor Cloudinary](https://github.com/capawesome-team/capacitor-cloudinary) plugin. Thanks to everyone who contributed to the project!

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Cloudinary Ltd. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Compass Plugin

Capacitor plugin for reading the device compass heading.

## Features

- 🧭 **Heading**: Read the current compass heading on demand.
- 🔄 **Live updates**: Listen for continuous heading changes.
- 🌍 **True north**: Read the true (geographic) north heading on iOS.
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/) and [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Compass plugin is typically used whenever an app needs to know which direction the device is pointing, for example:

- **Compass apps**: Build a classic compass UI that rotates with live heading updates.
- **Navigation**: Rotate a map or show the direction the user is currently facing.
- **Outdoor activities**: Guide hikers or geocachers towards a target bearing.
- **Points of interest**: Point the user towards a fixed geographic direction, such as a landmark or a prayer direction.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How heading data fits into navigation and wayfinding features.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-compass` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-compass
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On the Web, all methods reject as unimplemented.

### iOS

#### Privacy Descriptions

The magnetic heading is available without any permission. To also read the true (geographic) north heading, location services must be enabled and the `NSLocationWhenInUseUsageDescription` key must be added to the `Info.plist` file of your app.

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to determine the true (geographic) north heading.</string>
```

If the key is missing or location permission is not granted, the `trueHeading` value is `null`.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check if the compass sensor is available, read the current heading, and listen for heading changes.

### Check if the compass sensor is available

Before reading the heading, you can check whether the device has a compass sensor. Only available on Android and iOS:

```
import { Compass } from '@capawesome/capacitor-compass';

const isAvailable = async () => {
  const { available } = await Compass.isAvailable();
  return available;
};
```

### Read the current heading

Get the most recent heading reading from the device's compass sensor. The result contains the magnetic heading, the true (geographic) heading if available, and the accuracy. Only available on Android and iOS:

```
import { Compass } from '@capawesome/capacitor-compass';

const getHeading = async () => {
  const heading = await Compass.getHeading();
  return heading;
};
```

### Listen for heading changes

Call `startHeadingUpdates()` to start emitting `headingChange` events and add a listener to receive continuous heading updates, for example to rotate a compass UI. Stop the updates when you no longer need them. Only available on Android and iOS:

```
import { Compass } from '@capawesome/capacitor-compass';

const startHeadingUpdates = async () => {
  await Compass.startHeadingUpdates();
};

const addHeadingChangeListener = async () => {
  await Compass.addListener('headingChange', heading => {
    console.log(heading);
  });
};

const stopHeadingUpdates = async () => {
  await Compass.stopHeadingUpdates();
};

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

## API

- [`getHeading()`](#getheading)
- [`isAvailable()`](#isavailable)
- [`startHeadingUpdates()`](#startheadingupdates)
- [`stopHeadingUpdates()`](#stopheadingupdates)
- [`addListener('headingChange', ...)`](#addlistenerheadingchange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getHeading()

```
getHeading() => Promise<GetHeadingResult>
```

Get the current device heading.

This method returns the most recent heading reading from the device's compass sensor.

Only available on Android and iOS.

**Returns:** `Promise<Heading>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the compass sensor is available on the device.

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### startHeadingUpdates()

```
startHeadingUpdates() => Promise<void>
```

Start emitting `headingChange` events.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### stopHeadingUpdates()

```
stopHeadingUpdates() => Promise<void>
```

Stop emitting `headingChange` events.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('headingChange', ...)

```
addListener(eventName: 'headingChange', listenerFunc: (event: HeadingChangeEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for heading changes.

Only available on Android and iOS.

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | `'headingChange'`          |
| **`listenerFunc`** | `(event: Heading) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### Heading

| Prop                  | Type     | Description                                                                                                                                           | Since                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`accuracy`**        | \`number | null\`                                                                                                                                                | The maximum deviation between the reported heading and the true heading in degrees. A negative value or `null` indicates that the accuracy is invalid or unknown.                                                                                                                                                                                                                                              |
| **`magneticHeading`** | `number` | The heading relative to magnetic north in degrees. The value ranges from `0` to `360`, where `0` means the device is pointing towards magnetic north. | 0.1.0                                                                                                                                                                                                                                                                                                                                                                                                          |
| **`trueHeading`**     | \`number | null\`                                                                                                                                                | The heading relative to true (geographic) north in degrees. The value ranges from `0` to `360`, where `0` means the device is pointing towards true north. Returns `null` if the true heading cannot be determined. On Android, this value is always `null`. On iOS, this value requires location services to be enabled and the `NSLocationWhenInUseUsageDescription` key to be set. Otherwise, it is `null`. |

#### IsAvailableResult

| Prop            | Type      | Description                                            | Since |
| --------------- | --------- | ------------------------------------------------------ | ----- |
| **`available`** | `boolean` | Whether the compass sensor is available on the device. | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetHeadingResult

`Heading`

#### HeadingChangeEvent

`Heading`

## FAQ

### How is this plugin different from other similar plugins?

It reads the device compass heading both on demand and as a continuous stream of updates, returning the magnetic heading, the accuracy, and — on iOS with location services — the true geographic heading. An `isAvailable()` check lets you confirm the sensor is present before you rely on it, and the whole surface is fully typed. It supports CocoaPods and Swift Package Manager on iOS and is actively maintained against the latest Capacitor version, giving you consistent heading data across Android and iOS.

### What is the difference between the magnetic heading and the true heading?

The `magneticHeading` value is the heading relative to magnetic north, while the `trueHeading` value is the heading relative to true (geographic) north. Both range from `0` to `360` degrees. The magnetic heading is always available, whereas the true heading can only be determined on iOS and may be `null`.

### Why is the `trueHeading` value always `null`?

On Android, the true heading is not supported and the value is always `null`. On iOS, reading the true heading requires location services to be enabled and the `NSLocationWhenInUseUsageDescription` key to be added to your app's `Info.plist` file, as described in the [Installation](#installation) section. If the key is missing or location permission is not granted, the value is `null`.

### Does this plugin work on the Web?

No, this plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented. You can use the `isAvailable()` method to check whether the compass sensor is available on the current device.

### Do I need any permissions to read the compass heading?

The magnetic heading is available without any permission on both Android and iOS. Only if you also want to read the true (geographic) north heading on iOS, location services must be enabled and the `NSLocationWhenInUseUsageDescription` key must be present in your `Info.plist` file.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure measured in hectopascals.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/compass/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/compass/LICENSE).

# Capacitor Contacts Plugin

Capacitor plugin to read, write, or select device contacts. Supports Android, iOS and Web with advanced features like contact groups, pagination, and native modals.

## Features

The Capacitor Contacts plugin is one of the most complete contact management solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 📇 **Contacts**: Create, update, delete and retrieve device contacts.
- 🔄 **Partial Updates**: Update only specific contact fields without affecting others - missing properties are preserved, null values delete fields.
- 📌 **Groups**: Create, update, delete and retrieve contact groups on iOS.
- 🎫 **Accounts**: Add contacts to specific accounts on Android.
- 📖 **Pagination**: Paginate through contacts to avoid performance issues.
- 🔍 **Filtering**: Filter contacts by ID, email, phone number, etc. (Coming soon!)
- 📱 **Native Modals**: Create, update and display contacts in native modals.
- 🎯 **Picking**: Let the user select a device contact.
- 🖼️ **Photos**: Set, update and retrieve contact photos.
- 🤝 **Compatibility**: Works alongside the [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/), [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Contacts plugin is typically used whenever an app needs to work with the device's address book, for example:

- **Contact selection**: Let users pick one or more contacts from the device, for example to invite friends or share content.
- **CRM and business apps**: Create, update, and delete contacts directly from your app, including photos, email addresses, phone numbers, and postal addresses.
- **Contact syncing**: Read device contacts with pagination and keep them in sync with your backend.
- **Contact organization**: Manage contact groups on iOS or add contacts to specific accounts on Android.
- **Native contact forms**: Display, create, and update contacts in native modals without building your own UI.

## Compatibility

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

## Guides

- [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/)
- [Announcing the Capacitor Contacts Plugin](https://capawesome.io/blog/announcing-the-capacitor-contacts-plugin/)
- [Exploring the Capacitor Contacts API](https://capawesome.io/blog/exploring-the-capacitor-contacts-api/)
- [Google Play Contacts Policy 2027 for Capacitor](https://capawesome.io/blog/capacitor-google-play-contacts-policy-2027/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-contacts` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-contacts
npx cap sync
```

### Android

#### Permissions

This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if you want to read contacts. -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Required if you want to write contacts. -->
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
```

`pickContacts(...)` requires the `READ_CONTACTS` permission below Android 17, because the contact picker grants access to the picked contact URI only, which does not expose any contact details. Pass the `property` option instead to let the user select a single phone number, email address or postal address, which never requires a permission. Apps that only need contact selection should use that option and omit `READ_CONTACTS`, as required by [Google Play's Contacts Permissions policy](https://support.google.com/googleplay/android-developer/answer/16926792).

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSContactsUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts:

```
<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to display them in the app.</string>
```

#### Entitlements

To access the `note` field of a contact, your app must have the `com.apple.developer.contacts.notes` entitlement. Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.contacts.notes) for more information.

If you don't need access to the `note` field, you can skip this step.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to create, update, delete, pick, retrieve, and display contacts, manage contact groups and accounts, and check availability and permissions.

### Create a contact

Create a new contact on the device with properties such as name, birthday, email addresses, phone numbers, and postal addresses. Only available on Android and iOS:

```
import { Contacts, EmailAddressType, PhoneNumberType, PostalAddressType } from '@capawesome-team/capacitor-contacts';

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      birthday: {
        day: 1,
        month: 1,
        year: 1990
      },
      givenName: 'John',
      familyName: 'Doe',
      emailAddresses: [
        {
          value: 'mail@example.com',
          type: EmailAddressType.Home,
          isPrimary: true
        }
      ],
      phoneNumbers: [
        {
          value: '1234567890',
          type: PhoneNumberType.Mobile,
          isPrimary: true
        }
      ],
      postalAddresses: [
        {
          street: '123 Main St',
          city: 'Springfield',
          state: 'IL',
          postalCode: '62701',
          country: 'USA',
          type: PostalAddressType.Home,
          isPrimary: true
        }
      ]
    }
  });
};
```

### Update or delete a contact

Update only specific fields of an existing contact without affecting others: missing properties are preserved, `null` values delete a field. You can also delete a contact by its ID. Only available on Android and iOS:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const updateContactById = async (id: string) => {
  await Contacts.updateContactById({
    id,
    contact: {
      givenName: 'John',
      familyName: 'Doe',
      birthday: null, // This will remove the birthday field from the contact
      note: undefined // This will preserve the existing note field
    }
  });
};

const deleteContactById = async (id: string) => {
  await Contacts.deleteContactById({ id });
};
```

### Pick contacts

Open the native contact picker and let the user select one or more contacts. Use the `fields` option to specify which contact properties should be returned and the `multiple` option to let the user select more than one contact:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const pickContacts = async () => {
  const { contacts } = await Contacts.pickContacts({
    fields: [
      'id',
      'givenName',
      'familyName',
      'emailAddresses',
      'phoneNumbers',
      'postalAddresses'
    ],
    multiple: true
  });
  return contacts;
};
```

### Retrieve contacts

Fetch a single contact by its ID or retrieve a list of contacts. Use the `limit` and `offset` options to paginate through large address books and `countContacts()` to get the total number of contacts. Only available on Android and iOS:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const getContactById = async (id: string) => {
  const { contact } = await Contacts.getContactById({ id });
  return contact;
};

const getContacts = async () => {
  const { contacts } = await Contacts.getContacts({
    fields: [
      'id',
      'givenName',
      'familyName',
      'emailAddresses',
      'phoneNumbers',
      'postalAddresses'
    ],
    limit: 10,
    offset: 0
  });
  return contacts;
};

const countContacts = async () => {
  const { total } = await Contacts.countContacts();
  return total;
};
```

### Display contacts in native modals

Show or edit a contact in the native contact modal instead of building your own UI. Only available on Android and iOS:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const displayContactById = async (id: string) => {
  await Contacts.displayContactById({ id });
};

const displayUpdateContactById = async (id: string) => {
  await Contacts.displayUpdateContactById({ id });
};
```

### Manage contact groups

Create, retrieve, and delete contact groups. Only available on iOS:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const createGroup = async () => {
  return Contacts.createGroup({
    group: {
      name: 'My Group'
    }
  });
};

const deleteGroupById = async (id: string) => {
  await Contacts.deleteGroupById({ id });
};

const getGroupById = async (id: string) => {
  const { group } = await Contacts.getGroupById({ id });
  return group;
};

const getGroups = async () => {
  const { groups } = await Contacts.getGroups();
  return groups;
};
```

### Retrieve accounts

Retrieve the accounts that contacts can be added to. Only available on Android:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const getAccounts = async () => {
  const { accounts } = await Contacts.getAccounts();
  return accounts;
};
```

### Check availability

Check whether the contacts API is supported and available on the current device before using it:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const isAvailable = async () => {
  const { isAvailable } = await Contacts.isAvailable();
  return isAvailable;
};

const isSupported = async () => {
  const { isSupported } = await Contacts.isSupported();
  return isSupported;
};
```

### Check and request permissions

Check and request permissions to access the device contacts. Only available on Android and iOS:

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const checkPermissions = async () => {
  return Contacts.checkPermissions();
};

const requestPermissions = async () => {
  return Contacts.requestPermissions();
};
```

## API

- [`countContacts()`](#countcontacts)
- [`createContact(...)`](#createcontact)
- [`createGroup(...)`](#creategroup)
- [`deleteContactById(...)`](#deletecontactbyid)
- [`deleteGroupById(...)`](#deletegroupbyid)
- [`displayContactById(...)`](#displaycontactbyid)
- [`displayCreateContact(...)`](#displaycreatecontact)
- [`displayUpdateContactById(...)`](#displayupdatecontactbyid)
- [`getAccounts()`](#getaccounts)
- [`getContactById(...)`](#getcontactbyid)
- [`getContacts(...)`](#getcontacts)
- [`getGroupById(...)`](#getgroupbyid)
- [`getGroups()`](#getgroups)
- [`isAvailable()`](#isavailable)
- [`isSupported()`](#issupported)
- [`openSettings()`](#opensettings)
- [`pickContact(...)`](#pickcontact)
- [`pickContacts(...)`](#pickcontacts)
- [`updateContactById(...)`](#updatecontactbyid)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions(...)`](#requestpermissions)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### countContacts()

```
countContacts() => Promise<CountContactsResult>
```

Count the number of contacts on the device.

Only available on Android and iOS.

**Returns:** `Promise<CountContactsResult>`

**Since:** 7.4.0

______________________________________________________________________

### createContact(...)

```
createContact(options: CreateContactOptions) => Promise<CreateContactResult>
```

Create a new contact on the device.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `CreateContactOptions` |

**Returns:** `Promise<CreateContactResult>`

**Since:** 7.0.0

______________________________________________________________________

### createGroup(...)

```
createGroup(options: CreateGroupOptions) => Promise<CreateGroupResult>
```

Create a new contact group on the device.

Only available on iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `CreateGroupOptions` |

**Returns:** `Promise<CreateGroupResult>`

**Since:** 7.4.0

______________________________________________________________________

### deleteContactById(...)

```
deleteContactById(options: DeleteContactByIdOptions) => Promise<void>
```

Delete a contact from the device.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `DeleteContactByIdOptions` |

**Since:** 7.0.0

______________________________________________________________________

### deleteGroupById(...)

```
deleteGroupById(options: DeleteGroupByIdOptions) => Promise<void>
```

Delete a contact group from the device.

Only available on iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `DeleteGroupByIdOptions` |

**Since:** 7.4.0

______________________________________________________________________

### displayContactById(...)

```
displayContactById(options: DisplayContactByIdOptions) => Promise<void>
```

Display an existing contact by identifier.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `DisplayContactByIdOptions` |

**Since:** 7.4.0

______________________________________________________________________

### displayCreateContact(...)

```
displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise<DisplayCreateContactResult>
```

Open a native modal to create a new device contact.

This allows the user to update the contact information before saving it and does not require any permissions.

Only available on Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `DisplayCreateContactOptions` |

**Returns:** `Promise<DisplayCreateContactResult>`

**Since:** 7.2.0

______________________________________________________________________

### displayUpdateContactById(...)

```
displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise<void>
```

Open a native modal to update a contact.

Only available on Android and iOS.

| Param         | Type                              |
| ------------- | --------------------------------- |
| **`options`** | `DisplayUpdateContactByIdOptions` |

**Since:** 7.4.0

______________________________________________________________________

### getAccounts()

```
getAccounts() => Promise<GetAccountsResult>
```

List all accounts on the device.

Only available on Android.

**Returns:** `Promise<GetAccountsResult>`

**Since:** 7.4.0

______________________________________________________________________

### getContactById(...)

```
getContactById(options: GetContactByIdOptions) => Promise<GetContactByIdResult>
```

Find a contact by identifier.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetContactByIdOptions` |

**Returns:** `Promise<GetContactByIdResult>`

**Since:** 7.0.0

______________________________________________________________________

### getContacts(...)

```
getContacts(options?: GetContactsOptions | undefined) => Promise<GetContactsResult>
```

List all contacts on the device.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetContactsOptions` |

**Returns:** `Promise<GetContactsResult>`

**Since:** 7.0.0

______________________________________________________________________

### getGroupById(...)

```
getGroupById(options: GetGroupByIdOptions) => Promise<GetGroupByIdResult>
```

Find a contact group by identifier.

Only available on iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GetGroupByIdOptions` |

**Returns:** `Promise<GetGroupByIdResult>`

**Since:** 7.4.0

______________________________________________________________________

### getGroups()

```
getGroups() => Promise<GetGroupsResult>
```

List all contact groups on the device.

Only available on iOS.

**Returns:** `Promise<GetGroupsResult>`

**Since:** 7.4.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether or not contacts is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 7.6.0

______________________________________________________________________

### isSupported()

```
isSupported() => Promise<IsSupportedResult>
```

Check if the contacts API is available on the device.

**Returns:** `Promise<IsSupportedResult>`

**Since:** 7.0.0

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Opens the native app settings page to allow the user to grant the app contacts permissions.

Only available on Android and iOS.

**Since:** 7.7.0

______________________________________________________________________

### pickContact(...)

```
pickContact(options?: PickContactsOptions | undefined) => Promise<PickContactResult>
```

Open the contact picker to select a contact from the device.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `PickContactsOptions` |

**Returns:** `Promise<PickContactsResult>`

**Since:** 7.0.0

______________________________________________________________________

### pickContacts(...)

```
pickContacts(options?: PickContactsOptions | undefined) => Promise<PickContactsResult>
```

Open the contact picker to select a contact from the device.

On Android, reading the selected contact requires the `READ_CONTACTS` permission below Android 17. Set the `property` option to select a single contact property instead, which never requires a permission.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `PickContactsOptions` |

**Returns:** `Promise<PickContactsResult>`

**Since:** 7.4.0

______________________________________________________________________

### updateContactById(...)

```
updateContactById(options: UpdateContactByIdOptions) => Promise<void>
```

Update an existing contact on the device.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `UpdateContactByIdOptions` |

**Since:** 7.4.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions to access contacts.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions to access contacts.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### Interfaces

#### CountContactsResult

| Prop        | Type     | Description             | Since |
| ----------- | -------- | ----------------------- | ----- |
| **`total`** | `number` | The number of contacts. | 7.4.0 |

#### CreateContactResult

| Prop     | Type     | Description                             | Since |
| -------- | -------- | --------------------------------------- | ----- |
| **`id`** | `string` | The identifier for the created contact. | 7.0.0 |

#### CreateContactOptions

| Prop          | Type                  | Description            | Since |
| ------------- | --------------------- | ---------------------- | ----- |
| **`contact`** | `Omit<Contact, 'id'>` | The contact to create. | 7.0.0 |

#### Contact

| Prop                   | Type              | Description                                                                                                                                                                     | Since |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`account`**          | `Account`         | The account associated with the contact. Only available on Android.                                                                                                             | 7.4.0 |
| **`birthday`**         | `Birthday`        | The birthday of the contact.                                                                                                                                                    | 7.3.0 |
| **`displayName`**      | `string`          | The formatted name of the contact as displayed by the device. This property is read-only and is ignored when creating or updating a contact. Only available on Android and iOS. | 8.1.0 |
| **`emailAddresses`**   | `EmailAddress[]`  | The list of email addresses for the contact.                                                                                                                                    | 7.0.0 |
| **`familyName`**       | `string`          | The family name of the contact. Only available on Android and iOS.                                                                                                              | 7.0.0 |
| **`givenName`**        | `string`          | The given name of the contact. Only available on Android and iOS.                                                                                                               | 7.0.0 |
| **`groupIds`**         | `string[]`        | The identifier of the groups the contact belongs to. Only available on iOS.                                                                                                     | 7.4.0 |
| **`id`**               | `string`          | The identifier for the contact. Only available on Android and iOS.                                                                                                              | 7.0.0 |
| **`jobTitle`**         | `string`          | The job title of the contact. Only available on Android and iOS.                                                                                                                | 7.0.0 |
| **`middleName`**       | `string`          | The middle name of the contact. Only available on Android and iOS.                                                                                                              | 7.0.0 |
| **`fullName`**         | `string`          | The full name of the contact. Only available on Web.                                                                                                                            | 7.0.0 |
| **`namePrefix`**       | `string`          | The name prefix of the contact. Only available on Android and iOS.                                                                                                              | 7.0.0 |
| **`nameSuffix`**       | `string`          | The name suffix of the contact. Only available on Android and iOS.                                                                                                              | 7.0.0 |
| **`note`**             | `string`          | A note about the contact. Only available on Android and iOS.                                                                                                                    | 7.0.0 |
| **`organizationName`** | `string`          | The organization name of the contact. Only available on Android and iOS.                                                                                                        | 7.0.0 |
| **`phoneNumbers`**     | `PhoneNumber[]`   | The list of phone numbers for the contact.                                                                                                                                      | 7.0.0 |
| **`photo`**            | `string`          | The photo of the contact as a base64 string. Only available on Android and iOS.                                                                                                 | 7.0.0 |
| **`postalAddresses`**  | `PostalAddress[]` | The list of postal addresses for the contact.                                                                                                                                   | 7.0.0 |
| **`urlAddresses`**     | `UrlAddress[]`    | The list of URL addresses for the contact. Only available on Android and iOS.                                                                                                   | 7.0.0 |

#### Account

| Prop       | Type     | Description                                  | Since |
| ---------- | -------- | -------------------------------------------- | ----- |
| **`name`** | `string` | The account name. Only available on Android. | 7.4.0 |
| **`type`** | `string` | The account type. Only available on Android. | 7.4.0 |

#### Birthday

| Prop        | Type     | Description                                                                                                                                               | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`day`**   | `number` | The day of the birthdate.                                                                                                                                 | 7.3.0 |
| **`month`** | `number` | The month of the birthdate.                                                                                                                               | 7.3.0 |
| **`year`**  | `number` | The year of the birthdate. On **Android**, this must be provided if the `day` and `month` are provided when using the `displayCreateContact(...)` method. | 7.3.0 |

#### EmailAddress

| Prop            | Type               | Description                                                                                                                             | Default                  | Since |
| --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |
| **`isPrimary`** | `boolean`          | Whether this email address is the primary one for the contact.                                                                          | `false`                  | 7.0.0 |
| **`label`**     | `string`           | A custom label for the email address. On **iOS**, this label is only set if the type is [`EmailAddressType.Custom`](#emailaddresstype). |                          | 7.0.0 |
| **`type`**      | `EmailAddressType` | The type of email address.                                                                                                              | `EmailAddressType.Other` | 7.0.0 |
| **`value`**     | `string`           | The email address.                                                                                                                      |                          | 7.0.0 |

#### PhoneNumber

| Prop            | Type              | Description                                                                                                                          | Default                 | Since |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | ----- |
| **`isPrimary`** | `boolean`         | Whether this email address is the primary one for the contact.                                                                       |                         | 7.0.0 |
| **`label`**     | `string`          | A custom label for the phone number. On **iOS**, this label is only set if the type is [`PhoneNumberType.Custom`](#phonenumbertype). |                         | 7.0.0 |
| **`type`**      | `PhoneNumberType` | The type of phone number.                                                                                                            | `PhoneNumberType.Other` | 7.0.0 |
| **`value`**     | `string`          | The phone number.                                                                                                                    |                         |       |

#### PostalAddress

| Prop                 | Type                | Description                                                                                                                                                                   | Default                   | Since |
| -------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----- |
| **`city`**           | `string`            | The city for the postal address.                                                                                                                                              |                           | 7.0.0 |
| **`country`**        | `string`            | The country for the postal address.                                                                                                                                           |                           | 7.0.0 |
| **`formatted`**      | `string`            | The formatted postal address.                                                                                                                                                 |                           | 7.0.0 |
| **`isoCountryCode`** | `string`            | The ISO country code for the postal address. Only available on iOS.                                                                                                           |                           | 7.0.0 |
| **`isPrimary`**      | `boolean`           | Whether this postal address is the primary one for the contact. Only available on Android and iOS.                                                                            | `false`                   | 7.0.0 |
| **`label`**          | `string`            | A custom label for the postal address. On **iOS**, this label is only set if the type is [`PostalAddressType.Custom`](#postaladdresstype). Only available on Android and iOS. |                           | 7.0.0 |
| **`neighborhood`**   | `string`            | The neighborhood for the postal address. Only available on Android and iOS.                                                                                                   |                           | 7.0.0 |
| **`postalCode`**     | `string`            | The postal code for the postal address. Only available on Android and iOS.                                                                                                    |                           | 7.0.0 |
| **`state`**          | `string`            | The state for the postal address.                                                                                                                                             |                           | 7.0.0 |
| **`street`**         | `string`            | The street for the postal address. Only available on Android and iOS.                                                                                                         |                           | 7.0.0 |
| **`type`**           | `PostalAddressType` | The type of postal address. Only available on Android and iOS.                                                                                                                | `PostalAddressType.Other` | 7.0.0 |

#### UrlAddress

| Prop        | Type             | Description                         | Default                | Since |
| ----------- | ---------------- | ----------------------------------- | ---------------------- | ----- |
| **`label`** | `string`         | A custom label for the URL address. |                        | 7.5.0 |
| **`type`**  | `UrlAddressType` | The type of URL address.            | `UrlAddressType.Other` | 7.5.0 |
| **`value`** | `string`         | The URL address.                    |                        |       |

#### CreateGroupResult

| Prop     | Type     | Description                           | Since |
| -------- | -------- | ------------------------------------- | ----- |
| **`id`** | `string` | The identifier for the created group. | 7.4.0 |

#### CreateGroupOptions

| Prop        | Type                | Description          | Since |
| ----------- | ------------------- | -------------------- | ----- |
| **`group`** | `Omit<Group, 'id'>` | The group to create. | 7.4.0 |

#### Group

| Prop       | Type     | Description                   | Since |
| ---------- | -------- | ----------------------------- | ----- |
| **`id`**   | `string` | The identifier for the group. | 7.4.0 |
| **`name`** | `string` | The name of the group.        | 7.4.0 |

#### DeleteContactByIdOptions

| Prop     | Type     | Description                     | Since |
| -------- | -------- | ------------------------------- | ----- |
| **`id`** | `string` | The identifier for the contact. | 7.0.0 |

#### DeleteGroupByIdOptions

| Prop     | Type     | Description                   | Since |
| -------- | -------- | ----------------------------- | ----- |
| **`id`** | `string` | The identifier for the group. | 7.4.0 |

#### DisplayContactByIdOptions

| Prop     | Type     | Description                               | Since |
| -------- | -------- | ----------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the contact to display. | 7.4.0 |

#### DisplayCreateContactResult

| Prop     | Type     | Description                                                                                                              | Since |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`id`** | `string` | The identifier for the created contact. On **Android**, you need the `readContacts` permission to return the identifier. | 7.4.0 |

#### DisplayCreateContactOptions

| Prop          | Type                  | Description                                         | Since |
| ------------- | --------------------- | --------------------------------------------------- | ----- |
| **`contact`** | `Omit<Contact, 'id'>` | The contact to display in the create contact modal. | 7.2.0 |

#### DisplayUpdateContactByIdOptions

| Prop     | Type     | Description                              | Since |
| -------- | -------- | ---------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the contact to update. | 7.4.0 |

#### GetAccountsResult

| Prop           | Type        | Description                                   | Since |
| -------------- | ----------- | --------------------------------------------- | ----- |
| **`accounts`** | `Account[]` | An array of available accounts on the device. | 7.4.0 |

#### GetContactByIdResult

| Prop          | Type      |
| ------------- | --------- |
| **`contact`** | \`Contact |

#### GetContactByIdOptions

| Prop         | Type                | Description                           | Default                                                                                                                                                                                                       | Since |
| ------------ | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`fields`** | `(keyof Contact)[]` | The fields to return for the contact. | `['birthday', 'displayName', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']` | 7.1.0 |
| **`id`**     | `string`            | The identifier for the contact.       |                                                                                                                                                                                                               | 7.0.0 |

#### GetContactsResult

| Prop           | Type        | Description                                                                                       | Since |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------- | ----- |
| **`contacts`** | `Contact[]` | The list of contacts on the device. **Note**: No photos are returned to avoid performance issues. | 7.0.0 |

#### GetContactsOptions

| Prop         | Type                | Description                             | Default                                                                                                                                                                            | Since |
| ------------ | ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`fields`** | `(keyof Contact)[]` | The fields to return for the contact.   | `['emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']` | 7.1.0 |
| **`limit`**  | `number`            | Limit the number of contacts returned.  | `20`                                                                                                                                                                               | 7.4.0 |
| **`offset`** | `number`            | Offset the number of contacts returned. | `0`                                                                                                                                                                                | 7.4.0 |

#### GetGroupByIdResult

| Prop        | Type    | Description | Since                                    |
| ----------- | ------- | ----------- | ---------------------------------------- |
| **`group`** | \`Group | null\`      | The group with the specified identifier. |

#### GetGroupByIdOptions

| Prop     | Type     | Description                   | Since |
| -------- | -------- | ----------------------------- | ----- |
| **`id`** | `string` | The identifier for the group. | 7.4.0 |

#### GetGroupsResult

| Prop         | Type      | Description                       | Since |
| ------------ | --------- | --------------------------------- | ----- |
| **`groups`** | `Group[]` | The list of groups on the device. | 7.4.0 |

#### IsAvailableResult

| Prop              | Type      | Description                                         | Since |
| ----------------- | --------- | --------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not contacts is available on the device. | 7.6.0 |

#### IsSupportedResult

| Prop              | Type      | Description                                                                                    | Since |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------- | ----- |
| **`isSupported`** | `boolean` | Whether the contacts API is available on the device. This is always `true` on Android and iOS. | 7.0.0 |

#### PickContactsResult

| Prop           | Type        | Description                                         | Since |
| -------------- | ----------- | --------------------------------------------------- | ----- |
| **`contacts`** | `Contact[]` | The selected contacts. Empty if none were selected. | 7.0.0 |

#### PickContactsOptions

| Prop           | Type                | Description                                                                                                                                                                                                                                                                | Default                                                                                                                                                                                                       | Since |
| -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`fields`**   | `(keyof Contact)[]` | The fields to return for the contact. On Android 17 and newer, the contact picker only lists contacts that have at least one of the requested fields and never returns the `account` and `note` fields. Only available on Android and iOS.                                 | `['birthday', 'displayName', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']` | 7.4.0 |
| **`multiple`** | `boolean`           | Whether to allow selecting multiple contacts. Ignored if the `property` option is set. On Android, only supported on Android 17 and newer, where the user can select at most 100 contacts.                                                                                 | `false`                                                                                                                                                                                                       | 7.0.0 |
| **`property`** | `ContactProperty`   | The contact property to select. If set, the user selects a single property instead of a whole contact. The result then only contains the `id`, the `displayName` and the selected property, but no permissions are required to read it. Only available on Android and iOS. |                                                                                                                                                                                                               | 8.1.0 |

#### UpdateContactByIdOptions

| Prop          | Type                            | Description                                                                                                                                                                 | Since |
| ------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`contact`** | `Nullable<Omit<Contact, 'id'>>` | The updated contact information. Missing properties are ignored and keep their existing values. Properties explicitly set to `null` (or empty arrays `[]`) will be deleted. | 8.0.0 |
| **`id`**      | `string`                        | The identifier for the contact.                                                                                                                                             | 8.0.0 |

#### PermissionStatus

| Prop                | Type                      | Description                                                               | Since |
| ------------------- | ------------------------- | ------------------------------------------------------------------------- | ----- |
| **`readContacts`**  | `ContactsPermissionState` | Permission state for reading contacts. Only available on Android and iOS. | 7.0.0 |
| **`writeContacts`** | `ContactsPermissionState` | Permission state for writing contacts. Only available on Android and iOS. | 7.0.0 |

#### RequestPermissionsOptions

| Prop              | Type                       | Description                 | Default                             | Since |
| ----------------- | -------------------------- | --------------------------- | ----------------------------------- | ----- |
| **`permissions`** | `ContactsPermissionType[]` | The permissions to request. | `['readContacts', 'writeContacts']` | 7.0.0 |

### Type Aliases

#### ContactField

`keyof Contact`

#### PickContactOptions

`PickContactsOptions`

#### PickContactResult

`PickContactsResult`

#### Nullable

Makes all properties of T nullable.

`{ [K in keyof T]: T[K] | null }`

#### ContactsPermissionState

`PermissionState | 'limited'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### ContactsPermissionType

`'readContacts' | 'writeContacts'`

### Enums

#### EmailAddressType

| Members      | Value      | Description                | Since |
| ------------ | ---------- | -------------------------- | ----- |
| **`Custom`** | `'CUSTOM'` |                            | 7.0.0 |
| **`Home`**   | `'HOME'`   |                            | 7.0.0 |
| **`ICloud`** | `'ICLOUD'` | Only available on iOS.     | 7.0.0 |
| **`Mobile`** | `'MOBILE'` | Only available on Android. | 7.0.0 |
| **`Other`**  | `'OTHER'`  |                            | 7.0.0 |
| **`School`** | `'SCHOOL'` | Only available on iOS.     | 7.0.0 |
| **`Work`**   | `'WORK'`   |                            | 7.0.0 |

#### PhoneNumberType

| Members           | Value            | Description                | Since |
| ----------------- | ---------------- | -------------------------- | ----- |
| **`Assistant`**   | `'ASSISTANT'`    | Only available on Android. | 7.0.0 |
| **`Callback`**    | `'CALLBACK'`     | Only available on Android. | 7.0.0 |
| **`Car`**         | `'CAR'`          | Only available on Android. | 7.0.0 |
| **`CompanyMain`** | `'COMPANY_MAIN'` | Only available on Android. | 7.0.0 |
| **`Custom`**      | `'CUSTOM'`       |                            | 7.0.0 |
| **`FaxHome`**     | `'FAX_HOME'`     |                            | 7.0.0 |
| **`FaxOther`**    | `'FAX_OTHER'`    |                            | 7.0.0 |
| **`FaxWork`**     | `'FAX_WORK'`     |                            | 7.0.0 |
| **`Home`**        | `'HOME'`         |                            | 7.0.0 |
| **`IPhone`**      | `'IPHONE'`       | Only available on iOS.     | 7.0.0 |
| **`Isdn`**        | `'ISDN'`         | Only available on Android. | 7.0.0 |
| **`Main`**        | `'MAIN'`         |                            | 7.0.0 |
| **`Mms`**         | `'MMS'`          | Only available on Android. | 7.0.0 |
| **`Mobile`**      | `'MOBILE'`       |                            | 7.0.0 |
| **`Other`**       | `'OTHER'`        |                            | 7.0.0 |
| **`Pager`**       | `'PAGER'`        |                            | 7.0.0 |
| **`Radio`**       | `'RADIO'`        | Only available on Android. | 7.0.0 |
| **`Telex`**       | `'TELEX'`        | Only available on Android. | 7.0.0 |
| **`TtyTdd`**      | `'TTY_TDD'`      | Only available on Android. | 7.0.0 |
| **`Work`**        | `'WORK'`         |                            | 7.0.0 |
| **`WorkMobile`**  | `'WORK_MOBILE'`  | Only available on Android. | 7.0.0 |
| **`WorkPager`**   | `'WORK_PAGER'`   | Only available on Android. | 7.0.0 |

#### PostalAddressType

| Members      | Value      | Since |
| ------------ | ---------- | ----- |
| **`Custom`** | `'CUSTOM'` | 7.0.0 |
| **`Home`**   | `'HOME'`   | 7.0.0 |
| **`Other`**  | `'OTHER'`  | 7.0.0 |
| **`Work`**   | `'WORK'`   | 7.0.0 |

#### UrlAddressType

| Members        | Value        | Description                | Since |
| -------------- | ------------ | -------------------------- | ----- |
| **`Blog`**     | `'BLOG'`     | Only available on Android. | 7.5.0 |
| **`Custom`**   | `'CUSTOM'`   |                            | 7.5.0 |
| **`Ftp`**      | `'FTP'`      | Only available on Android. | 7.5.0 |
| **`Home`**     | `'HOME'`     |                            | 7.5.0 |
| **`Homepage`** | `'HOMEPAGE'` |                            | 7.5.0 |
| **`Other`**    | `'OTHER'`    |                            | 7.5.0 |
| **`Profile`**  | `'PROFILE'`  | Only available on Android. | 7.5.0 |
| **`School`**   | `'SCHOOL'`   | Only available on iOS.     | 7.5.0 |
| **`Work`**     | `'WORK'`     |                            | 7.5.0 |

#### ContactProperty

| Members             | Value             | Description                             | Since |
| ------------------- | ----------------- | --------------------------------------- | ----- |
| **`EmailAddress`**  | `'emailAddress'`  | A single email address of the contact.  | 8.1.0 |
| **`PhoneNumber`**   | `'phoneNumber'`   | A single phone number of the contact.   | 8.1.0 |
| **`PostalAddress`** | `'postalAddress'` | A single postal address of the contact. | 8.1.0 |

## FAQ

### Do I need any permissions to access contacts?

It depends. `displayCreateContact(...)` never needs a permission, and neither does `pickContacts(...)` on iOS. On Android, `pickContacts(...)` needs the `READ_CONTACTS` permission below Android 17, unless you pass the `property` option to select a single contact property instead. Every other method needs access to the address book: on Android, add the `READ_CONTACTS` and/or `WRITE_CONTACTS` permissions to your `AndroidManifest.xml` file (see [Installation](#installation)); on iOS, add the `NSContactsUsageDescription` key to your `Info.plist` file. At runtime, use `checkPermissions()` and `requestPermissions()` to manage the permission state, and `openSettings()` to send the user to the native app settings if the permission was denied.

### How do I update only specific fields of a contact?

The `updateContactById(...)` method supports partial updates. Properties that are missing from the contact object are preserved, while properties explicitly set to `null` are deleted from the contact. See the [usage example](#update-or-delete-a-contact) above.

### Are contact groups and accounts available on all platforms?

No. Contact groups (`createGroup(...)`, `getGroups()`, `getGroupById(...)`, and `deleteGroupById(...)`) are only available on iOS. Accounts (`getAccounts()`) are only available on Android, where you can add contacts to a specific account.

### How do I handle large address books without performance issues?

Use the `limit` and `offset` options of `getContacts(...)` to paginate through the contacts instead of loading all of them at once. Additionally, only request the contact properties you actually need via the `fields` option, and use `countContacts()` to determine the total number of contacts.

### How is this plugin different from the Capacitor Community Contacts plugin?

This plugin offers advanced features such as partial updates, contact groups on iOS, accounts on Android, pagination, native modals, and contact photos, and comes with priority support from the Capawesome Team. You can find a detailed comparison in the guide [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/): Open the native email composer.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.
- [SIM](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information.
- [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/LICENSE).

# Capacitor Crisp Plugin

Unofficial Capacitor plugin for [Crisp](https://crisp.chat/).[1](#fn:1)

## Features

The Capacitor Crisp plugin is a comprehensive integration of the Crisp chat SDKs for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 💬 **Chatbox**: Open the Crisp chatbox with a single method call.
- 👤 **User Identity**: Set the user's email, nickname, phone number, avatar, and company.
- 🔐 **Identity Verification**: Verify the user's identity with an HMAC-SHA256 email signature.
- 🧩 **Session Data**: Attach custom data, segments, and events to the session.
- 📚 **Helpdesk**: Open the helpdesk search or a specific helpdesk article.
- 🔔 **Push Notifications**: Interoperate with Firebase Cloud Messaging (Android) and APNs (iOS).
- 📡 **Typed Events**: Listen for chat, message, and session events with typed listeners.
- 🌐 **Typed Web SDK**: Uses the official `crisp-sdk-web` package on the web.
- 🤝 **Compatibility**: Looking for a different chat SDK? Check out the [Intercom](https://capawesome.io/docs/sdks/capacitor/intercom/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Crisp plugin is typically used wherever you want to offer live chat and customer support inside your app, for example:

- **Customer support**: Let users chat with your support team directly from within the app.
- **User identification**: Attach the signed-in user's email, name, and company to every conversation.
- **Self-service**: Point users to helpdesk articles without leaving the app.
- **Contextual data**: Enrich conversations with session data, segments, and events based on user behavior.
- **Re-engagement**: Notify users about new operator replies via push notifications.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-crisp` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-crisp crisp-sdk-web
npx cap sync
```

This plugin requires a [Crisp](https://crisp.chat/) account. You can find your **Website ID** in the Crisp dashboard under **Settings → Website Settings → Setup & Integrations**.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$crispSdkVersion` version of `im.crisp:crisp-sdk` (default: `2.0.22`)
- `$firebaseMessagingVersion` version of `com.google.firebase:firebase-messaging` (default: `24.1.1`)

#### Minimum SDK Version

The Crisp Android SDK requires a minimum SDK version of `24`. Make sure the `minSdkVersion` in your app's `variables.gradle` file is set to `24` or higher.

#### Multidex

The Crisp Android SDK requires [multidex](https://developer.android.com/build/multidex) to be enabled. Enable it in your app's `android/app/build.gradle` file:

```
android {
  defaultConfig {
    multiDexEnabled true
  }
}
```

#### FileProvider

The Crisp Android SDK ships its own `FileProvider` (used for chat attachments) with the authority `${applicationId}.im.crisp.client.uploadfileprovider`. This authority is merged automatically and does not conflict with your app's own `FileProvider`, so no additional configuration is required.

#### Push Notifications

Push notifications on Android are delivered through [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging). There are two ways to integrate them:

**Option A — Crisp's own notification service (zero-config)**

If your app does not use its own `FirebaseMessagingService`, add the following service to the `application` tag of your `android/app/src/main/AndroidManifest.xml` file:

```
<service
  android:name="im.crisp.client.external.notification.CrispNotificationService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>
```

**Option B — Share an existing `FirebaseMessagingService`**

If your app already receives push notifications (e.g. via [`@capacitor-firebase/messaging`](https://github.com/capawesome-team/capacitor-firebase)), forward incoming messages to Crisp from your JavaScript code:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';
import { Crisp } from '@capawesome/capacitor-crisp';

FirebaseMessaging.addListener('notificationReceived', async ({ notification }) => {
  const data = notification.data ?? {};
  const { crisp } = await Crisp.isCrispPushNotification({ data });
  if (crisp) {
    await Crisp.handlePushNotification({ data });
  }
});
```

You can enable or disable Crisp push notifications at runtime with `setNotificationsEnabled(...)`.

### iOS

The Crisp iOS SDK can be integrated via Swift Package Manager (recommended) or CocoaPods.

> [!NOTE] Crisp will stop publishing new CocoaPods releases in September 2026. We recommend using Swift Package Manager. If your app still uses CocoaPods, plan to migrate to Swift Package Manager before then.

#### Info.plist

The Crisp chatbox lets users send image and file attachments. Add the following keys to your `ios/App/App/Info.plist` file so users can attach photos:

```
<key>NSCameraUsageDescription</key>
<string>The app needs access to your camera to send photos in the chat.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>The app needs access to your photo library to send photos in the chat.</string>
```

#### Push Notifications

Push notifications on iOS are delivered through [Apple Push Notification service (APNs)](https://developer.apple.com/documentation/usernotifications):

1. Enable the **Push Notifications** capability for your app target in Xcode.
1. Register for remote notifications (e.g. via [`@capacitor-firebase/messaging`](https://github.com/capawesome-team/capacitor-firebase) or `@capacitor/push-notifications`).

The plugin automatically forwards the APNs device token to Crisp once your app has registered for remote notifications, so no additional token handling is required.

Use `setShouldPromptForNotificationPermission(...)` to control whether the Crisp SDK prompts the user for the notification permission.

### Web

The web implementation loads the Crisp chatbox from Crisp's CDN at runtime. This requires an active network connection. If your app enforces a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), make sure to allow the Crisp domains (e.g. `client.crisp.chat`, `*.crisp.chat`, and `wss://*.relay.crisp.chat`).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Configure the plugin

Call `configure(...)` once before all other methods:

```
import { Crisp } from '@capawesome/capacitor-crisp';

const configure = async () => {
  await Crisp.configure({
    websiteId: 'YOUR_WEBSITE_ID',
  });
};
```

### Open the chat

Open the Crisp chatbox:

```
import { Crisp } from '@capawesome/capacitor-crisp';

const openChat = async () => {
  await Crisp.openChat();
};
```

### Set the user

Set the information of the current user, optionally with identity verification:

```
import { Crisp } from '@capawesome/capacitor-crisp';

const setUser = async () => {
  await Crisp.setUser({
    email: 'jane.doe@example.com',
    emailSignature: 'YOUR_HMAC_SIGNATURE',
    nickname: 'Jane Doe',
  });
};
```

### Attach session data

Attach custom data, segments, and events to the current session:

```
import { Crisp, SessionEventColor } from '@capawesome/capacitor-crisp';

const attachSessionData = async () => {
  await Crisp.setSessionString({ key: 'plan', value: 'pro' });
  await Crisp.setSessionSegment({ segment: 'checkout' });
  await Crisp.pushSessionEvent({ name: 'purchase', color: SessionEventColor.Green });
};
```

### Listen for events

Listen for chat, message, and session events:

```
import { Crisp } from '@capawesome/capacitor-crisp';

const addListeners = async () => {
  await Crisp.addListener('sessionLoaded', ({ sessionId }) => {
    console.log('Session loaded:', sessionId);
  });
  await Crisp.addListener('messageReceived', ({ content }) => {
    console.log('Message received:', content);
  });
};
```

## API

- [`configure(...)`](#configure)
- [`handlePushNotification(...)`](#handlepushnotification)
- [`isCrispPushNotification(...)`](#iscrisppushnotification)
- [`openChat()`](#openchat)
- [`openHelpdeskArticle(...)`](#openhelpdeskarticle)
- [`pushSessionEvent(...)`](#pushsessionevent)
- [`resetSession()`](#resetsession)
- [`searchHelpdesk()`](#searchhelpdesk)
- [`setCompany(...)`](#setcompany)
- [`setLocale(...)`](#setlocale)
- [`setNotificationsEnabled(...)`](#setnotificationsenabled)
- [`setSessionBool(...)`](#setsessionbool)
- [`setSessionInt(...)`](#setsessionint)
- [`setSessionSegment(...)`](#setsessionsegment)
- [`setSessionString(...)`](#setsessionstring)
- [`setShouldPromptForNotificationPermission(...)`](#setshouldpromptfornotificationpermission)
- [`setTokenId(...)`](#settokenid)
- [`setUser(...)`](#setuser)
- [`addListener('chatClosed', ...)`](#addlistenerchatclosed-)
- [`addListener('chatOpened', ...)`](#addlistenerchatopened-)
- [`addListener('messageReceived', ...)`](#addlistenermessagereceived-)
- [`addListener('messageSent', ...)`](#addlistenermessagesent-)
- [`addListener('sessionLoaded', ...)`](#addlistenersessionloaded-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### configure(...)

```
configure(options: ConfigureOptions) => Promise<void>
```

Configure the plugin with your Crisp website ID.

This method must be called before any other method.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `ConfigureOptions` |

**Since:** 0.1.0

______________________________________________________________________

### handlePushNotification(...)

```
handlePushNotification(options: HandlePushNotificationOptions) => Promise<void>
```

Handle an incoming push notification that belongs to Crisp.

Use `isCrispPushNotification(...)` to check whether the notification belongs to Crisp before calling this method.

Only available on Android.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `HandlePushNotificationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isCrispPushNotification(...)

```
isCrispPushNotification(options: IsCrispPushNotificationOptions) => Promise<IsCrispPushNotificationResult>
```

Check whether an incoming push notification belongs to Crisp.

Only available on Android.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `IsCrispPushNotificationOptions` |

**Returns:** `Promise<IsCrispPushNotificationResult>`

**Since:** 0.1.0

______________________________________________________________________

### openChat()

```
openChat() => Promise<void>
```

Open the chat.

**Since:** 0.1.0

______________________________________________________________________

### openHelpdeskArticle(...)

```
openHelpdeskArticle(options: OpenHelpdeskArticleOptions) => Promise<void>
```

Open a specific helpdesk article.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `OpenHelpdeskArticleOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pushSessionEvent(...)

```
pushSessionEvent(options: PushSessionEventOptions) => Promise<void>
```

Push a session event to the current session.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `PushSessionEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### resetSession()

```
resetSession() => Promise<void>
```

Reset the current session.

This clears the current session and starts a new one on the next interaction.

**Since:** 0.1.0

______________________________________________________________________

### searchHelpdesk()

```
searchHelpdesk() => Promise<void>
```

Open the helpdesk with the search view.

**Since:** 0.1.0

______________________________________________________________________

### setCompany(...)

```
setCompany(options: SetCompanyOptions) => Promise<void>
```

Set the company of the current user.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetCompanyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setLocale(...)

```
setLocale(options: SetLocaleOptions) => Promise<void>
```

Set the locale of the chatbox.

On Android and iOS, the chatbox follows the language of the app.

Only available on Web.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetLocaleOptions` |

**Since:** 0.1.2

______________________________________________________________________

### setNotificationsEnabled(...)

```
setNotificationsEnabled(options: SetNotificationsEnabledOptions) => Promise<void>
```

Enable or disable push notifications.

Only available on Android.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SetNotificationsEnabledOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setSessionBool(...)

```
setSessionBool(options: SetSessionBoolOptions) => Promise<void>
```

Set a boolean value for the given key in the current session.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SetSessionBoolOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setSessionInt(...)

```
setSessionInt(options: SetSessionIntOptions) => Promise<void>
```

Set an integer value for the given key in the current session.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetSessionIntOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setSessionSegment(...)

```
setSessionSegment(options: SetSessionSegmentOptions) => Promise<void>
```

Set the segment of the current session.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `SetSessionSegmentOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setSessionString(...)

```
setSessionString(options: SetSessionStringOptions) => Promise<void>
```

Set a string value for the given key in the current session.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetSessionStringOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setShouldPromptForNotificationPermission(...)

```
setShouldPromptForNotificationPermission(options: SetShouldPromptForNotificationPermissionOptions) => Promise<void>
```

Set whether the user should be prompted for the notification permission.

Only available on iOS.

| Param         | Type                                              |
| ------------- | ------------------------------------------------- |
| **`options`** | `SetShouldPromptForNotificationPermissionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setTokenId(...)

```
setTokenId(options: SetTokenIdOptions) => Promise<void>
```

Set the token ID of the current user.

The token ID is used to restore a session across devices and logins. You may also set it directly via `configure(...)`.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetTokenIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUser(...)

```
setUser(options: SetUserOptions) => Promise<void>
```

Set the information of the current user.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `SetUserOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('chatClosed', ...)

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

Called when the chat is closed.

| Param              | Type           |
| ------------------ | -------------- |
| **`eventName`**    | `'chatClosed'` |
| **`listenerFunc`** | `() => void`   |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('chatOpened', ...)

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

Called when the chat is opened.

| Param              | Type           |
| ------------------ | -------------- |
| **`eventName`**    | `'chatOpened'` |
| **`listenerFunc`** | `() => void`   |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('messageReceived', ...)

```
addListener(eventName: 'messageReceived', listenerFunc: (event: MessageReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a message is received from the operator.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'messageReceived'`                     |
| **`listenerFunc`** | `(event: MessageReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('messageSent', ...)

```
addListener(eventName: 'messageSent', listenerFunc: (event: MessageSentEvent) => void) => Promise<PluginListenerHandle>
```

Called when a message is sent by the user.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'messageSent'`                     |
| **`listenerFunc`** | `(event: MessageSentEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('sessionLoaded', ...)

```
addListener(eventName: 'sessionLoaded', listenerFunc: (event: SessionLoadedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the session is loaded.

This is also the recommended way to get the session ID.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'sessionLoaded'`                     |
| **`listenerFunc`** | `(event: SessionLoadedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ConfigureOptions

| Prop            | Type     | Description                           | Since |
| --------------- | -------- | ------------------------------------- | ----- |
| **`tokenId`**   | `string` | The token ID of the current user.     | 0.1.0 |
| **`websiteId`** | `string` | The website ID of your Crisp website. | 0.1.0 |

#### HandlePushNotificationOptions

| Prop       | Type                      | Description                        | Since |
| ---------- | ------------------------- | ---------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data of the push notification. | 0.1.0 |

#### IsCrispPushNotificationResult

| Prop        | Type      | Description                                     | Since |
| ----------- | --------- | ----------------------------------------------- | ----- |
| **`crisp`** | `boolean` | Whether the push notification belongs to Crisp. | 0.1.0 |

#### IsCrispPushNotificationOptions

| Prop       | Type                      | Description                        | Since |
| ---------- | ------------------------- | ---------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data of the push notification. | 0.1.0 |

#### OpenHelpdeskArticleOptions

| Prop           | Type     | Description                   | Since |
| -------------- | -------- | ----------------------------- | ----- |
| **`category`** | `string` | The category of the article.  | 0.1.0 |
| **`id`**       | `string` | The ID (slug) of the article. | 0.1.0 |
| **`locale`**   | `string` | The locale of the article.    | 0.1.0 |
| **`title`**    | `string` | The title of the article.     | 0.1.0 |

#### PushSessionEventOptions

| Prop        | Type                | Description             | Default                  | Since |
| ----------- | ------------------- | ----------------------- | ------------------------ | ----- |
| **`color`** | `SessionEventColor` | The color of the event. | `SessionEventColor.Blue` | 0.1.0 |
| **`name`**  | `string`            | The name of the event.  |                          | 0.1.0 |

#### SetCompanyOptions

| Prop              | Type                    | Description                                            | Since |
| ----------------- | ----------------------- | ------------------------------------------------------ | ----- |
| **`description`** | `string`                | The description of the company.                        | 0.1.0 |
| **`employment`**  | `SetCompanyEmployment`  | The employment information of the user at the company. | 0.1.0 |
| **`geolocation`** | `SetCompanyGeolocation` | The geolocation of the company.                        | 0.1.0 |
| **`name`**        | `string`                | The name of the company.                               | 0.1.0 |
| **`url`**         | `string`                | The URL of the company.                                | 0.1.0 |

#### SetCompanyEmployment

| Prop        | Type     | Description                               | Since |
| ----------- | -------- | ----------------------------------------- | ----- |
| **`role`**  | `string` | The role of the user at the company.      | 0.1.0 |
| **`title`** | `string` | The job title of the user at the company. | 0.1.0 |

#### SetCompanyGeolocation

| Prop          | Type     | Description                 | Since |
| ------------- | -------- | --------------------------- | ----- |
| **`city`**    | `string` | The city of the company.    | 0.1.0 |
| **`country`** | `string` | The country of the company. | 0.1.0 |

#### SetLocaleOptions

| Prop         | Type     | Description                                     | Since |
| ------------ | -------- | ----------------------------------------------- | ----- |
| **`locale`** | `string` | The locale of the chatbox as an ISO 639-1 code. | 0.1.2 |

#### SetNotificationsEnabledOptions

| Prop          | Type      | Description                                   | Since |
| ------------- | --------- | --------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether push notifications should be enabled. | 0.1.0 |

#### SetSessionBoolOptions

| Prop        | Type      | Description                    | Since |
| ----------- | --------- | ------------------------------ | ----- |
| **`key`**   | `string`  | The key of the session data.   | 0.1.0 |
| **`value`** | `boolean` | The value of the session data. | 0.1.0 |

#### SetSessionIntOptions

| Prop        | Type     | Description                    | Since |
| ----------- | -------- | ------------------------------ | ----- |
| **`key`**   | `string` | The key of the session data.   | 0.1.0 |
| **`value`** | `number` | The value of the session data. | 0.1.0 |

#### SetSessionSegmentOptions

| Prop          | Type     | Description                 | Since |
| ------------- | -------- | --------------------------- | ----- |
| **`segment`** | `string` | The segment of the session. | 0.1.0 |

#### SetSessionStringOptions

| Prop        | Type     | Description                    | Since |
| ----------- | -------- | ------------------------------ | ----- |
| **`key`**   | `string` | The key of the session data.   | 0.1.0 |
| **`value`** | `string` | The value of the session data. | 0.1.0 |

#### SetShouldPromptForNotificationPermissionOptions

| Prop          | Type      | Description                                                          | Since |
| ------------- | --------- | -------------------------------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether the user should be prompted for the notification permission. | 0.1.0 |

#### SetTokenIdOptions

| Prop          | Type     | Description                       | Since |
| ------------- | -------- | --------------------------------- | ----- |
| **`tokenId`** | `string` | The token ID of the current user. | 0.1.0 |

#### SetUserOptions

| Prop                 | Type     | Description                                                                                                                                                                                            | Since |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`avatarUrl`**      | `string` | The URL of the user's avatar.                                                                                                                                                                          | 0.1.0 |
| **`email`**          | `string` | The email address of the user.                                                                                                                                                                         | 0.1.0 |
| **`emailSignature`** | `string` | The HMAC-SHA256 signature of the user's email address for identity verification. The signature must be generated on your backend using your Crisp secret key. Never expose the secret key in your app. | 0.1.0 |
| **`nickname`**       | `string` | The nickname of the user.                                                                                                                                                                              | 0.1.0 |
| **`phone`**          | `string` | The phone number of the user.                                                                                                                                                                          | 0.1.0 |

#### PluginListenerHandle

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

#### MessageReceivedEvent

| Prop          | Type     | Description | Since                                                                                                              |
| ------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| **`content`** | \`string | null\`      | The text content of the message. This is `null` if the message has no text content (e.g. a file or audio message). |

#### MessageSentEvent

| Prop          | Type     | Description | Since                                                                                                              |
| ------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| **`content`** | \`string | null\`      | The text content of the message. This is `null` if the message has no text content (e.g. a file or audio message). |

#### SessionLoadedEvent

| Prop            | Type     | Description                   | Since |
| --------------- | -------- | ----------------------------- | ----- |
| **`sessionId`** | `string` | The ID of the loaded session. | 0.1.0 |

### Enums

#### SessionEventColor

| Members      | Value      | Since |
| ------------ | ---------- | ----- |
| **`Black`**  | `'BLACK'`  | 0.1.0 |
| **`Blue`**   | `'BLUE'`   | 0.1.0 |
| **`Brown`**  | `'BROWN'`  | 0.1.0 |
| **`Green`**  | `'GREEN'`  | 0.1.0 |
| **`Grey`**   | `'GREY'`   | 0.1.0 |
| **`Orange`** | `'ORANGE'` | 0.1.0 |
| **`Pink`**   | `'PINK'`   | 0.1.0 |
| **`Purple`** | `'PURPLE'` | 0.1.0 |
| **`Red`**    | `'RED'`    | 0.1.0 |
| **`Yellow`** | `'YELLOW'` | 0.1.0 |

## Platform Support

Not every Crisp SDK feature is available on all platforms. The following table lists the per-platform differences of the plugin's API:

| Method                                          | Android | iOS | Web |
| ----------------------------------------------- | ------- | --- | --- |
| `setSessionBool(...)`                           | ✅      | ✅  | ✅  |
| `isCrispPushNotification(...)`                  | ✅      | ❌  | ❌  |
| `handlePushNotification(...)`                   | ✅      | ❌  | ❌  |
| `setNotificationsEnabled(...)`                  | ✅      | ❌  | ❌  |
| `setShouldPromptForNotificationPermission(...)` | ❌      | ✅  | ❌  |
| `setLocale(...)`                                | ❌      | ❌  | ✅  |

On iOS, the Crisp SDK detects and handles its own push notifications internally once the APNs device token has been forwarded, so the JavaScript `isCrispPushNotification(...)` and `handlePushNotification(...)` methods are not available there.

The Crisp Android and iOS SDKs do not provide a locale override, so the `setLocale(...)` method is only available on the web. The native chatbox follows the language of the app. To change it at runtime, change the language of the app, e.g. with the [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/) plugin.

The following features of the Crisp SDKs are intentionally not part of this plugin's initial release: unread message count, bot scenarios, and audio/video calls. [Open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) if you need any of them.

## FAQ

### Do I need a Crisp account to use this plugin?

Yes. This plugin wraps the official Crisp SDKs, which require an active [Crisp](https://crisp.chat/) account and a website ID.

### How is this plugin different from other similar plugins?

This plugin exposes the Crisp SDKs through a fully typed API, including a strongly typed listener for each event and dedicated helpdesk methods. Identity verification is built in through email-signature HMAC, and push notifications are handled entirely through Crisp's public API. It ships a typed web implementation alongside Android and iOS, supports Swift Package Manager ahead of the CocoaPods sunset, and stays unopinionated by never forcing an automatic show or hide of the chatbox. It is actively maintained and backed by dedicated support.

### How do I get the session ID?

Listen for the `sessionLoaded` event. The event payload contains the `sessionId`. There is no synchronous getter, because the session is loaded asynchronously.

### How does identity verification work?

Generate an HMAC-SHA256 signature of the user's email address on your backend using your Crisp secret key, then pass it as the `emailSignature` option of `setUser(...)`. Never expose your secret key in your app.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Formbricks](https://capawesome.io/docs/sdks/capacitor/formbricks/): Unofficial Capacitor plugin for Formbricks to run in-app surveys.
- [Intercom](https://capawesome.io/docs/sdks/capacitor/intercom/): Unofficial Capacitor plugin for the Intercom live chat and customer support platform.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for the PostHog product analytics platform.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/crisp/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/crisp/LICENSE).

## Third-Party Notices

The Crisp Android and iOS SDKs are proprietary, closed-source binaries provided by Crisp IM SAS. This plugin only declares them as dependencies (via Maven, CocoaPods, and Swift Package Manager) and does not bundle or modify them. Using the plugin requires an active Crisp account and website ID. The MIT license of this plugin covers the wrapper code only, not the Crisp SDKs.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Crisp IM SAS or any of its affiliates or subsidiaries. "Crisp" is a trademark of Crisp IM SAS. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Datetime Picker Plugin

Capacitor plugin for seamless date and time selection with advanced features like localization, theming, and more. Available for Android and iOS.

## Features

The Capacitor Datetime Picker plugin is one of the most feature-rich date and time selection solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📅 **Multiple modes**: Date, time, datetime, and month picker modes.
- 🌍 **Localization**: Support for BCP 47 language tags.
- 🎨 **Theming**: Auto, light, and dark theme support.
- ⚡ **Custom formats**: Define your own date/time format strings.
- 🔒 **Min/Max constraints**: Set minimum and maximum selectable dates/times.
- 📱 **Native UI**: Uses platform-specific picker components.
- ⚙️ **Flexible configuration**: Customizable button texts and picker modes.
- 🤝 **Compatibility**: Works alongside the [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/), [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) and [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Datetime Picker plugin is typically used whenever an app needs the user to enter a date or time, for example:

- **Appointment booking**: Let users pick a date and time for a reservation and restrict the selection with minimum and maximum constraints.
- **Profile forms**: Ask for a date of birth with a native, localized date picker.
- **Reminders and alarms**: Let users choose a time of day using the native time picker, optionally with a custom minute interval on iOS.
- **Reports and statements**: Let users select a month and year only, for example to filter a monthly report, using the `month` mode.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-datetime-picker` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome-team/capacitor-datetime-picker
npx cap sync
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to present a date, time, or datetime picker, and how to let the user pick a month and year only.

### Present a date, time, or datetime picker

Open the native picker with the `present(...)` method. Use the `mode` option to choose between a date, time, or datetime picker, and customize the theme, locale, and button texts as needed. Only available on Android and iOS:

```
import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const present = async () => {
  const date = new Date('1995-12-24T02:23:00');

  const { value } = await DatetimePicker.present({
    cancelButtonText: 'Cancel',
    doneButtonText: 'Ok',
    mode: 'time',
    value: date.toISOString(),
    theme: 'dark',
    locale: 'en-US',
  });

  return value;
};
```

### Let the user pick a month and year only

Use the `month` mode to let the user pick a month and year without a day or time, for example to filter a monthly report. The returned value is the first day of the selected month:

```
import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const presentMonth = async () => {
  const { value } = await DatetimePicker.present({
    cancelButtonText: 'Cancel',
    doneButtonText: 'Ok',
    mode: 'month',
    value: '2026-05',
    format: 'yyyy-MM',
    locale: 'en-US',
  });

  return value;
};
```

## API

- [`present(...)`](#present)
- [`cancel()`](#cancel)
- [Interfaces](#interfaces)

### present(...)

```
present(options?: PresentOptions | undefined) => Promise<PresentResult>
```

Open the datetime picker.

An error is thrown if the input is canceled or dismissed by the user.

On Android, the picker is dismissed (the promise rejects with the `dismissed` error code) if the system language, font size or layout direction changes while it is open.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `PresentOptions` |

**Returns:** `Promise<PresentResult>`

**Since:** 0.0.1

______________________________________________________________________

### cancel()

```
cancel() => Promise<void>
```

Cancel the currently active datetime picker.

If there is no active picker, this method does nothing.

Only available on Android and iOS.

**Since:** 7.2.0

______________________________________________________________________

### Interfaces

#### PresentResult

| Prop        | Type     | Description                                                                                          | Since |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`value`** | `string` | The value entered by the user. The format of this value matches the value of the `format` parameter. | 0.0.1 |

#### PresentOptions

| Prop                        | Type        | Description                                                                                                                                                                                                                                                            | Default                                                                                                                                                                       | Since                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`cancelButtonText`**      | `string`    | The cancel button text.                                                                                                                                                                                                                                                | `'Cancel'`                                                                                                                                                                    | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`doneButtonText`**        | `string`    | The done button text.                                                                                                                                                                                                                                                  | `'Ok'`                                                                                                                                                                        | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`format`**                | `string`    | The format in which values are received and returned.                                                                                                                                                                                                                  | `'yyyy-MM-dd'T'HH:​mm:ss.sss'Z''`                                                                                                                                              | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`locale`**                | `string`    | BCP 47 language tag to define the language of the UI.                                                                                                                                                                                                                  |                                                                                                                                                                               | 0.0.2                                                                                                                                                                                                                                                                                                                                                          |
| **`max`**                   | `string`    | The latest date and time to accept. The format of this value must match the value of the `format` parameter. This value must specify a date string later than or equal to the one specified by the `min` attribute.                                                    |                                                                                                                                                                               | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`min`**                   | `string`    | The earliest date and time to accept. The format of this value must match the value of the `format` parameter. This value must specify a date string earlier than or equal to the one specified by the `max` attribute.                                                |                                                                                                                                                                               | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`mode`**                  | \`'date'    | 'time'                                                                                                                                                                                                                                                                 | 'datetime'                                                                                                                                                                    | 'month'\`                                                                                                                                                                                                                                                                                                                                                      |
| **`theme`**                 | \`'auto'    | 'light'                                                                                                                                                                                                                                                                | 'dark'\`                                                                                                                                                                      | Choose the theme that the datetime picker should have. With `auto` the system theme is used. This value overwrites the `theme` configuration value. On iOS 26 and later, the picker uses the system's Liquid Glass sheet, so the theme only selects its light or dark appearance. Only available on Android and iOS. Spinner options only available on Android |
| **`value`**                 | `string`    | The predefined value when opening the picker. The format of this value must match the value of the `format` parameter.                                                                                                                                                 |                                                                                                                                                                               | 0.0.1                                                                                                                                                                                                                                                                                                                                                          |
| **`androidTimePickerMode`** | \`'clock'   | 'spinner'\`                                                                                                                                                                                                                                                            | Whether to use the spinner or clock mode for the time picker on Android. This value overwrites the `androidTimePickerMode` configuration value. Only available on Android.    |                                                                                                                                                                                                                                                                                                                                                                |
| **`androidDatePickerMode`** | \`'spinner' | 'calendar'\`                                                                                                                                                                                                                                                           | Whether to use the calendar or spinner mode for the date picker on Android. This value overwrites the `androidDatePickerMode` configuration value. Only available on Android. |                                                                                                                                                                                                                                                                                                                                                                |
| **`minuteInterval`**        | `number`    | The minute interval of the time picker. This controls the granularity of the minute selector (e.g., 15 for 0, 15, 30, 45). The value must be evenly divisible into 60. Only available on iOS when using time or datetime modes. On Android, this parameter is ignored. | `1`                                                                                                                                                                           | 7.1.0                                                                                                                                                                                                                                                                                                                                                          |

## FAQ

### What happens when the user cancels the picker?

The `present(...)` method throws an error if the input is canceled or dismissed by the user. Make sure to catch this error in your code, for example to keep the previous value.

### How can I close the picker programmatically?

Use the `cancel()` method to cancel the currently active datetime picker, for example when your app is sent to the background. If there is no active picker, this method does nothing.

### How do I restrict which dates the user can select?

Use the `min` and `max` options of the `present(...)` method to define the earliest and latest date and time to accept. The format of both values must match the value of the `format` parameter.

### How do I let the user pick only a month and year?

Set the `mode` option to `month`. Unlike the other modes, the month picker uses a custom (non-native) UI on both platforms, because neither Android nor iOS provide a native month-only picker. The returned value is the first day of the selected month at 00:00:00 local time. See the [usage example](#let-the-user-pick-a-month-and-year-only) above.

### Can I change the language and theme of the picker?

Yes, use the `locale` option with a BCP 47 language tag to define the language of the UI, and the `theme` option to choose between `auto`, `light`, and `dark`. With `auto`, the system theme is used.

### Does this plugin work on the Web?

No, this plugin is only available on Android and iOS, where it uses platform-specific picker components. The `present(...)` and `cancel()` methods are not available on the Web.

## Related Plugins

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/): Show native action sheets.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Display native alert, confirm, and prompt dialogs.
- [Localization](https://capawesome.io/docs/sdks/capacitor/localization/): Read the user's preferred locales to localize the picker.
- [Option Picker](https://capawesome.io/docs/sdks/capacitor/option-picker/): Let the user pick an option from a list with a native picker.

## Credits

The iOS implementation of this plugin is based on [RPicker](https://github.com/rheyansh/RPicker) which is licensed under [MIT](https://github.com/rheyansh/RPicker/blob/master/LICENSE).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/datetime-picker/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/datetime-picker/LICENSE).

# Capacitor Device Info Plugin

Capacitor plugin to read device information, such as the model, manufacturer, operating system, memory, and a per-install identifier.

## Features

- 🆔 **Identifier**: Read a unique per-install identifier for the device.
- 📱 **Information**: Read the model, manufacturer, operating system, and more.
- 🧠 **Memory**: Read the total memory of the device and the memory used by the app.
- ⏱️ **Uptime**: Read how long the device has been running since its last boot.
- 🖥️ **Cross-platform**: Support for Android, iOS, and Web.
- 🤝 **Compatibility**: Works alongside the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/) and [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Device Info plugin is typically used whenever an app needs to know more about the device it is running on, for example:

- **Bug reports and support**: Attach the device model, manufacturer, operating system version, and WebView version to support tickets or crash reports.
- **Device registration**: Use the per-install identifier to register a device on your backend without collecting personal data.
- **Adaptive user interfaces**: Adjust your layout based on the device type, for example phone versus tablet.
- **Feature gating**: Enable or disable features depending on the Android SDK version or the major iOS version.
- **Diagnostics**: Monitor the memory used by your app or detect whether it is running on an emulator or simulator.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-device-info` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-device-info
npx cap sync
```

No additional permissions or configuration are required on any platform.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read the device identifier, read device information, and read the device uptime.

### Read the device identifier

Get a unique per-install identifier for the device, for example to register the device on your backend. See the [API documentation](#getid) for when the identifier is reset on each platform:

```
import { DeviceInfo } from '@capawesome/capacitor-device-info';

const getId = async () => {
  const { identifier } = await DeviceInfo.getId();
  return identifier;
};
```

### Read device information

Get information about the device, such as the model, manufacturer, operating system, device type, and memory. Fields that a platform cannot determine are `null` (see [Platform Support](#platform-support)):

```
import { DeviceInfo } from '@capawesome/capacitor-device-info';

const getInfo = async () => {
  const info = await DeviceInfo.getInfo();
  return info;
};
```

### Read the device uptime

Get the time the device has been running since its last boot, in milliseconds. Only available on Android and iOS:

```
import { DeviceInfo } from '@capawesome/capacitor-device-info';

const getUptime = async () => {
  const { uptime } = await DeviceInfo.getUptime();
  return uptime;
};
```

## API

- [`getId()`](#getid)
- [`getInfo()`](#getinfo)
- [`getUptime()`](#getuptime)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getId()

```
getId() => Promise<GetIdResult>
```

Get a unique identifier for the device.

On **Android**, the identifier is the `ANDROID_ID` value, which is unique per app-signing key, user, and device. It is reset when the app is reinstalled after the signing key changes or the device is factory reset.

On **iOS**, the identifier is the `identifierForVendor` value, which is unique per vendor and device. It is reset when all apps from the vendor are uninstalled.

On **Web**, the identifier is a random UUID that is persisted in the browser's `localStorage`. It is reset when the browser storage is cleared.

**Returns:** `Promise<GetIdResult>`

**Since:** 0.1.0

______________________________________________________________________

### getInfo()

```
getInfo() => Promise<GetInfoResult>
```

Get information about the device.

**Returns:** `Promise<GetInfoResult>`

**Since:** 0.1.0

______________________________________________________________________

### getUptime()

```
getUptime() => Promise<GetUptimeResult>
```

Get the time the device has been running since its last boot, in milliseconds.

Only available on Android and iOS.

**Returns:** `Promise<GetUptimeResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetIdResult

| Prop             | Type     | Description                          | Since |
| ---------------- | -------- | ------------------------------------ | ----- |
| **`identifier`** | `string` | The unique identifier of the device. | 0.1.0 |

#### GetInfoResult

| Prop                    | Type              | Description                                                                                                                        | Since                                                                                                                                                                                                               |
| ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`androidSdkVersion`** | \`number          | null\`                                                                                                                             | The Android SDK version number (API level). Returns `null` on platforms other than Android. Only available on Android.                                                                                              |
| **`deviceType`**        | `DeviceType`      | The type of the device.                                                                                                            | 0.1.0                                                                                                                                                                                                               |
| **`iosVersion`**        | \`number          | null\`                                                                                                                             | The major version number of iOS. Returns `null` on platforms other than iOS. Only available on iOS.                                                                                                                 |
| **`isVirtual`**         | `boolean`         | Whether the app is running on a virtual device (simulator or emulator).                                                            | 0.1.0                                                                                                                                                                                                               |
| **`manufacturer`**      | `string`          | The manufacturer of the device.                                                                                                    | 0.1.0                                                                                                                                                                                                               |
| **`model`**             | `string`          | The model identifier of the device. On **iOS**, this is the internal model identifier (e.g. `iPhone13,4`), not the marketing name. | 0.1.0                                                                                                                                                                                                               |
| **`name`**              | \`string          | null\`                                                                                                                             | The name of the device. On **iOS 16 and newer**, a generic device name (e.g. `iPhone`) is returned unless the app has the required entitlement. Returns `null` if the name cannot be determined.                    |
| **`operatingSystem`**   | `OperatingSystem` | The operating system of the device.                                                                                                | 0.1.0                                                                                                                                                                                                               |
| **`osVersion`**         | `string`          | The version of the operating system.                                                                                               | 0.1.0                                                                                                                                                                                                               |
| **`platform`**          | `Platform`        | The platform the app is running on.                                                                                                | 0.1.0                                                                                                                                                                                                               |
| **`totalMemory`**       | \`number          | null\`                                                                                                                             | The total amount of memory of the device, in bytes. Returns `null` if the total memory cannot be determined. Only available on Android and iOS.                                                                     |
| **`usedMemory`**        | \`number          | null\`                                                                                                                             | The amount of memory used by the app, in bytes. Returns `null` if the used memory cannot be determined. Only available on Android and iOS.                                                                          |
| **`webViewVersion`**    | \`string          | null\`                                                                                                                             | The version of the WebView that renders the app. On **iOS**, the version of the operating system is returned, because the WebKit version is tied to it. Returns `null` if the WebView version cannot be determined. |

#### GetUptimeResult

| Prop         | Type     | Description                                                                | Since |
| ------------ | -------- | -------------------------------------------------------------------------- | ----- |
| **`uptime`** | `number` | The time the device has been running since its last boot, in milliseconds. | 0.1.0 |

### Type Aliases

#### DeviceType

The type of a device.

- `phone`: A handheld phone-sized device.
- `tablet`: A tablet-sized device.
- `desktop`: A desktop or laptop computer.
- `tv`: A television or set-top box.
- `unknown`: The type could not be determined.

`'phone' | 'tablet' | 'desktop' | 'tv' | 'unknown'`

#### OperatingSystem

The operating system of a device.

`'android' | 'ios' | 'windows' | 'mac' | 'unknown'`

#### Platform

The platform an app is running on.

`'android' | 'ios' | 'web'`

## Platform Support

The plugin returns `null` for any field that a platform cannot determine. The following table shows which fields of the `getInfo()` result are available on each platform:

| Property            | Android | iOS | Web              |
| ------------------- | ------- | --- | ---------------- |
| `androidSdkVersion` | ✅      | ❌  | ❌               |
| `deviceType`        | ✅      | ✅  | ✅ (best-effort) |
| `iosVersion`        | ❌      | ✅  | ❌               |
| `isVirtual`         | ✅      | ✅  | ✅               |
| `manufacturer`      | ✅      | ✅  | ❌               |
| `model`             | ✅      | ✅  | ✅ (best-effort) |
| `name`              | ✅      | ✅  | ❌               |
| `operatingSystem`   | ✅      | ✅  | ✅ (best-effort) |
| `osVersion`         | ✅      | ✅  | ✅ (best-effort) |
| `platform`          | ✅      | ✅  | ✅               |
| `totalMemory`       | ✅      | ✅  | ❌               |
| `usedMemory`        | ✅      | ✅  | ❌               |
| `webViewVersion`    | ✅      | ✅  | ✅ (best-effort) |

The `getUptime()` method is only available on Android and iOS.

## Migration from `@capacitor/device`

This plugin can be used as a replacement for the official [`@capacitor/device`](https://capacitorjs.com/docs/apis/device) plugin. The following table shows how the methods map:

| `@capacitor/device` | `@capawesome/capacitor-device-info`                                                    |
| ------------------- | -------------------------------------------------------------------------------------- |
| `getId()`           | `getId()`                                                                              |
| `getInfo()`         | `getInfo()`                                                                            |
| `getBatteryInfo()`  | Use the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/) plugin           |
| `getLanguageCode()` | Use the [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugin |
| `getLanguageTag()`  | Use the [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugin |

## FAQ

### How is this plugin different from other similar plugins?

It gathers a wide range of device details through one fully typed API — model, manufacturer, operating system, a per-install identifier, total and used memory, device type, virtual-device detection, WebView version, and uptime — with consistent behavior across Android, iOS, and the Web. Fields a platform cannot determine are returned as `null`, and the package is actively maintained against the latest Capacitor and OS versions. If you only need the platform name, a minimal setup is enough; if you want a complete, honest picture of the device, this plugin is built for exactly that.

### How stable is the identifier returned by `getId`?

The identifier is unique per install. On Android, it is the `ANDROID_ID` value, which is reset when the app is reinstalled after the signing key changes or the device is factory reset. On iOS, it is the `identifierForVendor` value, which is reset when all apps from the vendor are uninstalled. On the Web, it is a random UUID persisted in the browser's `localStorage`, which is reset when the browser storage is cleared.

### Can this plugin replace the official `@capacitor/device` plugin?

Yes, this plugin can be used as a replacement for the official `@capacitor/device` plugin. The `getId()` and `getInfo()` methods map directly, while battery information and language settings are covered by the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/) and [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugins. See the [migration table](#migration-from-capacitordevice) above.

### Why is the device name always a generic value like `iPhone` on iOS?

On iOS 16 and newer, a generic device name is returned unless the app has the required entitlement from Apple. If the name cannot be determined at all, the `name` property is `null`.

### Why are some fields `null` on my platform?

The plugin returns `null` for any field that a platform cannot determine. For example, `totalMemory` and `usedMemory` are only available on Android and iOS, and `androidSdkVersion` is only available on Android. See the [Platform Support](#platform-support) section for a complete overview.

### Can I get the battery level or the device language with this plugin?

No, this plugin focuses on device information such as the model, manufacturer, operating system, and memory. For battery information, use the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/) plugin. For the user's language and locale preferences, use the [Localization](https://capawesome.io/docs/sdks/capacitor/localization/) plugin.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/): Access battery information.
- [Localization](https://capawesome.io/docs/sdks/capacitor/localization/): Read the user's localization preferences, such as preferred locales and time zone.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/device-info/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/device-info/LICENSE).

# Capacitor Dialog Plugin

Capacitor plugin for native alert, confirm, and prompt dialogs.

## Features

- 💬 **Alert**: Display a native alert dialog with a single button.
- ❓ **Confirm**: Ask the user to confirm or cancel an action.
- ⌨️ **Prompt**: Request text input from the user.
- 🌐 **Cross-platform**: Works on Android, iOS, and the web.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/), [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) and [Toast](https://capawesome.io/docs/sdks/capacitor/toast/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Dialog plugin is typically used whenever an app needs a quick native interaction with the user, for example:

- **Confirmations**: Ask the user to confirm a destructive action, such as deleting an item, before executing it.
- **Notices**: Inform the user about the result of an action, such as saved changes or an error, with a simple alert.
- **Quick text input**: Ask the user for a short text value, such as a name, without building a custom form.
- **Native look and feel**: Replace the browser's `window.alert`, `window.confirm`, and `window.prompt` with native dialogs on Android and iOS.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-dialog` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-dialog
npx cap sync
```

### Android

No additional configuration is required for this plugin.

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to display an alert dialog, ask the user for confirmation, and request text input from the user.

### Display an alert dialog

Show a message with a single button, for example to inform the user about the result of an action:

```
import { Dialog } from '@capawesome/capacitor-dialog';

const alert = async () => {
  await Dialog.alert({
    title: 'Success',
    message: 'Your changes have been saved.',
  });
};
```

### Ask the user for confirmation

Show a confirmation dialog with two buttons. The result tells you whether the user confirmed the dialog:

```
import { Dialog } from '@capawesome/capacitor-dialog';

const confirm = async () => {
  const { value } = await Dialog.confirm({
    title: 'Confirm',
    message: 'Do you want to delete this item?',
  });
  console.log('Confirmed:', value);
};
```

### Request text input from the user

Show a prompt dialog with a text input, a confirm and a cancel button. The result contains the entered value. If the user cancels the dialog, the promise is rejected with the `CANCELED` error code:

```
import { Dialog, ErrorCode } from '@capawesome/capacitor-dialog';

const prompt = async () => {
  try {
    const { value } = await Dialog.prompt({
      title: 'Name',
      message: 'What is your name?',
      inputPlaceholder: 'Enter your name',
    });
    console.log('Value:', value);
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user canceled the dialog.');
    }
  }
};
```

## API

- [`alert(...)`](#alert)
- [`confirm(...)`](#confirm)
- [`prompt(...)`](#prompt)
- [Interfaces](#interfaces)

### alert(...)

```
alert(options: AlertOptions) => Promise<void>
```

Display an alert dialog with a single button.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `AlertOptions` |

**Since:** 0.1.0

______________________________________________________________________

### confirm(...)

```
confirm(options: ConfirmOptions) => Promise<ConfirmResult>
```

Display a confirmation dialog with two buttons.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ConfirmOptions` |

**Returns:** `Promise<ConfirmResult>`

**Since:** 0.1.0

______________________________________________________________________

### prompt(...)

```
prompt(options: PromptOptions) => Promise<PromptResult>
```

Display a prompt dialog with a text input, a confirm and a cancel button.

If the user selects the cancel button or dismisses the dialog, the promise is rejected with the `CANCELED` error code.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `PromptOptions` |

**Returns:** `Promise<PromptResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AlertOptions

| Prop              | Type     | Description                                                                                                         | Default | Since |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`buttonTitle`** | `string` | The title of the button that confirms the dialog. On the web, the button title cannot be customized and is ignored. | `'OK'`  | 0.1.0 |
| **`message`**     | `string` | The message to display in the dialog.                                                                               |         | 0.1.0 |
| **`title`**       | `string` | The title of the dialog. On the web, the title cannot be customized and is ignored.                                 |         | 0.1.0 |

#### ConfirmResult

| Prop        | Type      | Description                            | Since |
| ----------- | --------- | -------------------------------------- | ----- |
| **`value`** | `boolean` | Whether the user confirmed the dialog. | 0.1.0 |

#### ConfirmOptions

| Prop                    | Type     | Description                                                                                                         | Default    | Since |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| **`cancelButtonTitle`** | `string` | The title of the button that cancels the dialog. On the web, the button title cannot be customized and is ignored.  | `'Cancel'` | 0.1.0 |
| **`message`**           | `string` | The message to display in the dialog.                                                                               |            | 0.1.0 |
| **`okButtonTitle`**     | `string` | The title of the button that confirms the dialog. On the web, the button title cannot be customized and is ignored. | `'OK'`     | 0.1.0 |
| **`title`**             | `string` | The title of the dialog. On the web, the title cannot be customized and is ignored.                                 |            | 0.1.0 |

#### PromptResult

| Prop        | Type     | Description                  | Since |
| ----------- | -------- | ---------------------------- | ----- |
| **`value`** | `string` | The value of the text input. | 0.1.0 |

#### PromptOptions

| Prop                    | Type     | Description                                                                                                         | Default    | Since |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| **`cancelButtonTitle`** | `string` | The title of the button that cancels the dialog. On the web, the button title cannot be customized and is ignored.  | `'Cancel'` | 0.1.0 |
| **`inputPlaceholder`**  | `string` | The placeholder of the text input. On the web, the placeholder cannot be customized and is ignored.                 |            | 0.1.0 |
| **`inputText`**         | `string` | The initial value of the text input.                                                                                |            | 0.1.0 |
| **`message`**           | `string` | The message to display in the dialog.                                                                               |            | 0.1.0 |
| **`okButtonTitle`**     | `string` | The title of the button that confirms the dialog. On the web, the button title cannot be customized and is ignored. | `'OK'`     | 0.1.0 |
| **`title`**             | `string` | The title of the dialog. On the web, the title cannot be customized and is ignored.                                 |            | 0.1.0 |

## Migrating from `@capacitor/dialog`

This plugin is largely API-compatible with the official [`@capacitor/dialog`](https://github.com/ionic-team/capacitor-plugins/tree/main/dialog) plugin, with a single difference: if the user cancels a prompt dialog, `prompt(...)` rejects with the `CANCELED` error code instead of resolving with a `cancelled` flag.

| `@capacitor/dialog`                      | `@capawesome/capacitor-dialog`                                   |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `alert({ title, message, buttonTitle })` | `alert({ title, message, buttonTitle })`                         |
| `confirm({ ... }) → { value }`           | `confirm({ ... }) → { value }`                                   |
| `prompt({ ... }) → { value, cancelled }` | `prompt({ ... }) → { value }`, rejects with `CANCELED` on cancel |

## FAQ

### How is this plugin different from other similar plugins?

It brings native alert, confirm, and prompt dialogs to Android, iOS, and the web through a single, fully typed API, using only official platform APIs so it stays safe for App Store and Google Play submissions. It supports both CocoaPods and Swift Package Manager on iOS and is actively maintained against the latest Capacitor and OS versions, with customizable button titles on Android and iOS. If you only need a quick native message, it is refreshingly simple to drop in; if you need consistent alert, confirm, and prompt behavior across every platform, it is built for exactly that.

### How is this plugin different from the official `@capacitor/dialog` plugin?

This plugin is largely API-compatible with the official `@capacitor/dialog` plugin, with a single difference: if the user cancels a prompt dialog, `prompt(...)` rejects with the `CANCELED` error code instead of resolving with a `cancelled` flag. See the [migration table](#migrating-from-capacitordialog) above for the complete method mapping.

### Can I customize the dialog buttons?

Yes, on Android and iOS you can customize the button titles using the `buttonTitle`, `okButtonTitle`, and `cancelButtonTitle` options. On the web, the button titles cannot be customized and are ignored, because the browser's built-in dialogs are used.

### How do I know whether the user canceled a prompt?

If the user cancels the dialog, the `prompt(...)` method rejects with the `CANCELED` error code, so catch the error and compare `error.code` with `ErrorCode.Canceled`. Otherwise, the result contains the entered text in the `value` property. For confirmation dialogs, the `value` property of the `confirm(...)` result tells you whether the user confirmed the dialog.

### Why is the dialog title not displayed on the web?

On the web, the title and button titles cannot be customized and are ignored, because the plugin uses the browser's built-in dialogs. Only the message is displayed. On Android and iOS, the title is fully supported.

### Is this plugin safe to use for App Store submissions?

Yes, the plugin uses only official platform APIs to display the dialogs, so it is safe to use in apps submitted to the Apple App Store and Google Play Store.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/): Show native action sheets.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Let the user pick a date and time with a native picker.
- [Toast](https://capawesome.io/docs/sdks/capacitor/toast/): Show native toast notifications.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/dialog/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/dialog/LICENSE).

# Capacitor Document Scanner Plugin

Capacitor plugin for scanning documents with the native, full-screen scanner on Android and iOS. Returns perspective-corrected images and an optional combined PDF.

## Features

The Capacitor Document Scanner plugin brings the platform's own document scanning experience to your Capacitor app. Here are some of the key features:

- 📱 **Native UI**: Uses the platform's built-in scanner (Google's ML Kit flow on Android, VisionKit on iOS).
- ✂️ **Perspective Correction**: Automatically detects edges and corrects the perspective of captured pages.
- 📄 **Multi-Page**: Capture multiple pages in a single scan.
- 🖼️ **JPEG Output**: Returns the scanned pages as JPEG files in the cache directory.
- 📑 **PDF Output**: Optionally generates a combined PDF document from the scanned pages.
- 🔒 **Public APIs Only**: Built exclusively on public platform APIs, so it is safe for App Review and resilient to OS updates.
- 🤝 **Compatibility**: Works hand in hand with the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/), [Printer](https://capawesome.io/docs/sdks/capacitor/printer/) and [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Document Scanner plugin is typically used whenever an app needs to digitize a physical document, for example:

- **Receipts and invoices**: Let users scan receipts for expense tracking.
- **Contracts and forms**: Capture signed documents as multi-page PDFs.
- **ID and cards**: Scan identity documents or business cards.
- **Notes and whiteboards**: Digitize handwritten notes or whiteboard content.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor Document Scanner Plugin](https://capawesome.io/blog/announcing-the-capacitor-document-scanner-plugin/): Scan documents with the native scanner UIs and get perspective-corrected pages and a combined PDF in two API calls.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-document-scanner` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-document-scanner
npx cap sync
```

### Android

The Google-provided scanner activity requests the camera permission itself, so no manifest changes are required.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$playServicesMlkitDocumentScannerVersion` version of `com.google.android.gms:play-services-mlkit-document-scanner` (default: `16.0.0`)

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

The scanner is delivered as an on-demand Google Play services module. It is **not** bundled with your app and is downloaded automatically the first time `scanDocument(...)` is called.

### iOS

Add the `NSCameraUsageDescription` key to the `Info.plist` file of your app to explain why your app needs access to the camera:

```
<key>NSCameraUsageDescription</key>
<string>The app needs access to the camera to scan documents.</string>
```

If the key is missing, `scanDocument(...)` rejects with a clear error message.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether document scanning is available, scan a document, and generate a PDF document from the scanned pages.

### Check the availability

Check whether document scanning is available on the device before starting a scan. Only available on Android and iOS:

```
import { DocumentScanner } from '@capawesome-team/capacitor-document-scanner';

const isAvailable = async () => {
  const { available } = await DocumentScanner.isAvailable();
  return available;
};
```

### Scan a document

Open the native scanner user interface to capture one or more pages. On both platforms, the scanner detects the edges of the document, corrects the perspective, and offers cropping, rotation and a review step before the pages are returned as JPEG files in the cache directory. On Android, you can change the editing capabilities with the `androidScannerMode` option and allow the user to import an existing image with the `androidGalleryImportAllowed` option. On iOS, image cleaning is applied automatically by the system. The promise rejects with the `SCAN_CANCELED` error code if the user cancels the scan. Only available on Android and iOS:

```
import { DocumentScanner } from '@capawesome-team/capacitor-document-scanner';

const scanDocument = async () => {
  const { scannedImages } = await DocumentScanner.scanDocument({
    imageQuality: 80,
    pageLimit: 5,
  });
  return scannedImages;
};
```

### Generate a PDF document

Set the `generatePdf` option to `true` to receive a combined PDF document of all scanned pages in the `pdf` property of the result. On Android, the PDF is generated by ML Kit. On iOS, it is composed from the scanned page images. Only available on Android and iOS:

```
import { DocumentScanner } from '@capawesome-team/capacitor-document-scanner';

const scanDocumentAsPdf = async () => {
  const { pdf } = await DocumentScanner.scanDocument({
    generatePdf: true,
  });
  return pdf;
};
```

You can pass the resulting `pdf` path to the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/) plugin to display it, to the [Printer](https://capawesome.io/docs/sdks/capacitor/printer/) plugin to print it, or to the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) plugin to open it in another app.

## API

- [`isAvailable()`](#isavailable)
- [`scanDocument(...)`](#scandocument)
- [Interfaces](#interfaces)
- [Enums](#enums)

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether document scanning is available on the device.

On **Android**, this resolves to `true` if Google Play services is available. The scanner module is downloaded on demand the first time `scanDocument(...)` is called.

On **iOS**, this resolves to `true` if the device supports document scanning (i.e. it has a camera and runs a supported iOS version).

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.0.1

______________________________________________________________________

### scanDocument(...)

```
scanDocument(options?: ScanDocumentOptions | undefined) => Promise<ScanDocumentResult>
```

Open the native document scanner user interface.

The scanner captures one or more pages, applies perspective correction, and returns the file paths of the scanned images and, optionally, a combined PDF document.

The scanner user interface is provided by the platform (Google's ML Kit flow on Android, VisionKit on iOS) and cannot be customized.

The promise rejects with the `SCAN_CANCELED` error code if the user cancels the scan.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ScanDocumentOptions` |

**Returns:** `Promise<ScanDocumentResult>`

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### IsAvailableResult

| Prop            | Type      | Description                                                  | Since |
| --------------- | --------- | ------------------------------------------------------------ | ----- |
| **`available`** | `boolean` | Whether or not document scanning is available on the device. | 0.0.1 |

#### ScanDocumentResult

| Prop                | Type       | Description                                                           | Since                                                                                                             |
| ------------------- | ---------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **`pdf`**           | \`string   | null\`                                                                | The path of the generated PDF document. Only set if the `generatePdf` option is set to `true`. Otherwise, `null`. |
| **`scannedImages`** | `string[]` | The paths of the scanned images as JPEG files in the cache directory. | 0.0.1                                                                                                             |

#### ScanDocumentOptions

| Prop                              | Type          | Description                                                                                                                                                                                                                             | Default            | Since |
| --------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| **`androidGalleryImportAllowed`** | `boolean`     | Whether or not the user is allowed to import an existing image from the gallery instead of capturing a new one with the camera. Only available on Android.                                                                              | `false`            | 0.0.1 |
| **`androidScannerMode`**          | `ScannerMode` | The mode of the scanner user interface. Only available on Android.                                                                                                                                                                      | `ScannerMode.Full` | 0.0.1 |
| **`generatePdf`**                 | `boolean`     | Whether or not to generate a combined PDF document from the scanned pages. The path of the generated PDF is returned in the `pdf` property of the result.                                                                               | `false`            | 0.0.1 |
| **`imageQuality`**                | `number`      | The JPEG quality of the scanned images. Must be a value between `0` (lowest quality) and `100` (highest quality).                                                                                                                       | `100`              | 0.0.1 |
| **`pageLimit`**                   | `number`      | The maximum number of pages that can be scanned. Must be greater than or equal to `1`. On **iOS**, the scanner cannot be limited to a specific number of pages. Instead, the returned pages are truncated to this value after scanning. | `10`               | 0.0.1 |

### Enums

#### ScannerMode

| Members              | Value                | Description                                                                                                           | Since |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Base`**           | `'BASE'`             | Basic editing capabilities (crop and rotate).                                                                         | 0.0.1 |
| **`BaseWithFilter`** | `'BASE_WITH_FILTER'` | Adds image filters (grayscale and automatic image enhancement) on top of the `Base` mode.                             | 0.0.1 |
| **`Full`**           | `'FULL'`             | Adds ML-based image cleaning capabilities (removes stains, fingers, and shadows) on top of the `BaseWithFilter` mode. | 0.0.1 |

## FAQ

### How is this plugin different from other similar plugins?

It brings the platform's native scanning experience to both Android (ML Kit) and iOS (VisionKit) through a single, unified API, with automatic edge detection and perspective correction, multi-page capture, JPEG output and an optional combined PDF. Everything is fully typed, built exclusively on public platform APIs so it stays safe for App Review, actively maintained against the latest OS and Capacitor versions, and backed by dedicated support. If you only need to scan on a single platform, a simpler setup can be enough; if you want consistent cross-platform scanning with PDF output, this plugin is designed for that.

### Is document scanning available on the web?

No. The `isAvailable(...)` and `scanDocument(...)` methods are only available on Android and iOS. On the web, both methods reject with an unimplemented error.

### Can I customize the scanner UI?

No. The plugin uses the scanner user interface of the platform (Google's ML Kit flow on Android, VisionKit on iOS) and does not draw any UI itself. Labels, buttons, icons and the scanning flow are defined by Google and Apple and therefore differ between the platforms. On Android, you can change the editing capabilities with the `androidScannerMode` option and allow the user to import an existing image with the `androidGalleryImportAllowed` option. On iOS, no options are available. If you want to suggest changes to the scanner UI, please report them to [Google](https://developers.google.com/ml-kit/community) or [Apple](https://feedbackassistant.apple.com/) directly.

### Why can't I limit the number of pages on iOS?

Apple's VisionKit does not expose a public API to stop the scanner after a specific number of pages. To avoid using private APIs (which would put your app at risk during App Review), the plugin truncates the returned pages to `pageLimit` after scanning instead.

### Where are the scanned files stored?

The scanned images and the generated PDF are stored in the app's cache directory. Stale files created by the plugin are cleaned up automatically when the plugin is loaded. Copy the files to a persistent location if you need to keep them.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open the scanned files in another app.
- [ML Kit Document Scanner](https://www.npmjs.com/package/@capacitor-mlkit/document-scanner): Scan documents with ML Kit Document Scanning on Android.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer.
- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/): Apply additional edits such as brightness or contrast adjustments.
- [Printer](https://capawesome.io/docs/sdks/capacitor/printer/): Print the scanned images or the generated PDF.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/document-scanner/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/document-scanner/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/document-scanner/LICENSE).

# Capacitor Electron Platform

Capacitor platform to build, run, and package desktop apps for macOS, Windows, and Linux with Electron.[1](#fn:1)

## Features

The Capacitor Electron platform brings your web app and your Capacitor plugins to the desktop. Here are some of the key features:

- 🖥️ **Cross-platform**: Build desktop apps for macOS, Windows, and Linux from one codebase.
- ⚡ **Familiar workflow**: `cap add`, `cap sync`, `cap run` — the same commands as iOS and Android.
- 🔌 **Plugin support**: Capacitor plugins with an Electron implementation work out of the box; plugins with a web implementation work automatically via fallback.
- ⚡ **Live Updates**: Deliver web-bundle updates over the air with the [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/) and Capawesome Cloud — the same workflow as on Android and iOS.
- 🔒 **Security-first**: Sandboxed renderer, context isolation, strict Content-Security-Policy, and validated IPC — enabled by default and not configurable.
- 🔗 **Deep links**: Custom URL schemes delivered through the standard `@capacitor/app` plugin's `appUrlOpen` event.
- 📱 **App lifecycle**: `appStateChange`, `pause`, and `resume` events, exactly like on mobile.
- ♻️ **Live reload**: Develop against your web dev server with full HMR.
- 📦 **Packaging**: Create installers with electron-builder, including automatic dependency vendoring.
- 🪟 **Window management**: Typed window options, state persistence, and hooks for trays and menus.
- 🧩 **Minimal scaffold**: You own a handful of small, stable files; all platform logic ships in the package and updates via `npm update`.
- 🔁 **Up-to-date**: Always supports the latest Capacitor and Electron versions.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-electron/issues) and we'll take a look!

## Use Cases

The Electron platform is typically used to bring an existing Capacitor app to the desktop, for example:

- **Desktop companion apps**: Ship your mobile app's functionality to macOS, Windows, and Linux without a rewrite.
- **Offline-first desktop tools**: Combine the platform with plugins like [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/) for fully offline desktop applications.
- **Instant desktop updates**: Ship fixes to the web layer without building and distributing a new installer, using [Live Updates](https://capawesome.io/docs/cloud/live-updates/electron/).
- **Internal business tools**: Distribute apps directly to your team without app stores.
- **Kiosk and point-of-sale apps**: Run your web app full screen on dedicated desktop hardware.
- **Deep-link driven workflows**: Handle custom URL schemes on the desktop exactly like on mobile.

## Compatibility

| Platform Version | Capacitor Version | Electron Version | Status         |
| ---------------- | ----------------- | ---------------- | -------------- |
| 0.x              | >=6.x.x           | >=28.x.x         | Active support |

> [!NOTE] On Capacitor 6 and 7, the Capacitor CLI ignores the exit code of platform hooks, so a failing `npx cap sync` still reports success — check the log output for `[capacitor-electron]` errors. Capacitor 8 fails the command properly.

## Guides

- [Capacitor Electron Platform: Build Desktop Apps](https://capawesome.io/blog/announcing-the-capacitor-electron-platform/)

## Installation

You can use our **AI-Assisted Setup** to add the platform. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-platforms
```

Then use the following prompt:

```
Use the `capacitor-platforms` skill from `capawesome-team/skills` to add the `@capawesome/capacitor-electron` platform to my project.
```

If you prefer **Manual Setup**, add the platform by running the following commands:

```
npm install @capawesome/capacitor-electron
npx cap add @capawesome/capacitor-electron
cd electron && npm install && cd ..
```

We recommend adding a `postinstall` script to your root `package.json` so the Electron dependencies are always installed together with your app dependencies:

```
{
  "scripts": {
    "postinstall": "cd electron && npm ci && cd .."
  }
}
```

The initial `cd electron && npm install` generates `electron/package-lock.json` — commit it so that `npm ci` works for every future install.

> [!NOTE] Always use the full package name with Capacitor CLI commands (e.g. `npx cap sync @capawesome/capacitor-electron`). A bare `npx cap sync electron` resolves to the `electron` npm package and silently does nothing.

The scaffolded `electron/` project contains only files you own:

| File                           | Purpose                                                 |
| ------------------------------ | ------------------------------------------------------- |
| `main.ts`                      | ~5 lines: imports the runtime and starts the app        |
| `capacitor.electron.config.ts` | Typed platform options (window, CSP, deep links, hooks) |
| `electron-builder.config.js`   | Packaging configuration                                 |
| `assets/`                      | App icons                                               |

Everything with logic lives in the versioned npm package and updates via `npm update` — your platform project never rots.

## Configuration

Platform options are configured in `electron/capacitor.electron.config.ts` with full type safety:

```
import { defineConfig } from '@capawesome/capacitor-electron/config';

export default defineConfig({
  window: {
    width: 1200,
    height: 800,
    minWidth: 800,
    minHeight: 600,
  },
  deepLinks: {
    scheme: 'myapp',
  },
});
```

Extension happens through typed options and hooks (`windowFactory`, `beforeReady`, `onWindowCreated`, CSP overrides) — never by owning runtime code.

### Plugin Configuration

Some plugins support platform-specific configuration on Android and iOS — for example, the Capacitor Live Update plugin reads a default channel from an Android string resource or an iOS `Info.plist` key so the build system can inject a value derived from the app version. The `plugins` section of `electron/capacitor.electron.config.ts` fills that role on Electron — generically, for every plugin. Because the file is executable TypeScript evaluated in the main process, values can be computed in code — no template syntax required.

It is merged over the `plugins` section of the Capacitor config **shallowly, per plugin key, and this section wins**: for each plugin, its keys override the matching keys in the Capacitor config while unmentioned keys survive; plugins present in only one of the two configs pass through unchanged. Everything outside `plugins` is untouched. The merge runs once at startup, before plugins receive their config.

```
import { defineConfig } from '@capawesome/capacitor-electron/config';
import packageJson from './package.json';

export default defineConfig({
  plugins: {
    LiveUpdate: {
      defaultChannel: `production-${packageJson.version}`,
    },
  },
});
```

> Importing `./package.json` requires `resolveJsonModule` in `electron/tsconfig.json` (already enabled in the scaffold).

## Demo

A working example can be found here: [capawesome-team/capacitor-electron](https://github.com/capawesome-team/capacitor-electron/tree/main/example)

## Usage

```
# Copy web assets + regenerate the plugin manifest
npx cap sync @capawesome/capacitor-electron

# Run the app (uses server.url for live reload when configured)
npx cap run @capawesome/capacitor-electron

# Open the built app
npx cap open @capawesome/capacitor-electron
```

### Live Reload

Set `server.url` in your Capacitor config to your dev server and run the app — the window loads the dev server with full HMR, and the plugin bridge works exactly as in production:

```
// capacitor.config.ts
const config: CapacitorConfig = {
  // ...
  server: {
    url: 'http://localhost:5173',
  },
};
```

```
npx vite &                                       # your web dev server
npx cap run @capawesome/capacitor-electron       # dev mode
```

In dev mode a documented, dev-only CSP relaxation is applied (inline scripts, eval, websockets — required by HMR runtimes), and the window automatically reconnects when the dev server restarts. Remove `server.url` (or use a production config) to serve the built web assets from the app bundle again.

### Deep Links

Declare the custom URL scheme in the platform configuration (see [Configuration](#configuration)) and listen to the standard `@capacitor/app` event:

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

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

Deep links opened while the app is running are routed to the running instance (single instance is enforced by default); the URL that launched the app is available via `App.getLaunchUrl()`.

### Splash Screen

Booting a desktop app is not instant: the platform runs every plugin's `load()` lifecycle hook (e.g. the [Live Update](https://capawesome.io/plugins/live-update/) plugin verifying and activating a bundle) *before* the main window is shown. A splash screen covers that gap so the app never appears frozen or blank.

A splash screen is shown automatically when a splash file exists in the electron app directory — no configuration required. Two files are looked up, in order:

1. `electron/assets/splash.html`
1. `electron/assets/splash.png`

The scaffold ships a neutral, theme-aware `assets/splash.html` by default. Migrating from [`@capacitor-community/electron`](https://github.com/capacitor-community/electron)? Its `assets/splash.png` is picked up unchanged.

Configure the splash screen in `electron/capacitor.electron.config.ts`:

```
import { defineConfig } from '@capawesome/capacitor-electron/config';

export default defineConfig({
  splashScreen: {
    // Custom file, relative to the electron app directory. Either an `.html`
    // file or an image (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`).
    path: 'assets/splash.html',
    width: 400,
    height: 300,
    backgroundColor: '#ffffff',
    // Keep the splash visible for at least this long, even on fast startups.
    minimumDurationMs: 0,
  },
});
```

| Option              | Type      | Default                                   | Description                                                                                |
| ------------------- | --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `enabled`           | `boolean` | shown when a splash file exists           | Set `false` to disable. Set `true` to require a splash file — boot fails if none is found. |
| `path`              | `string`  | `assets/splash.html`, `assets/splash.png` | Splash file relative to the electron app directory.                                        |
| `width`             | `number`  | `400`                                     | Window width in pixels.                                                                    |
| `height`            | `number`  | `300`                                     | Window height in pixels.                                                                   |
| `backgroundColor`   | `string`  | `'#ffffff'`                               | Window background and the canvas behind an image splash.                                   |
| `minimumDurationMs` | `number`  | `0`                                       | Minimum time the splash stays visible.                                                     |

**HTML vs. image:** an `.html` file is loaded directly, so you get full control over layout, fonts, and animation. An image is centered (`object-fit: contain`) on a `backgroundColor` canvas — convenient for a logo, but static.

The splash window is deliberately kept outside the plugin bridge: it is frameless, sandboxed, has no preload and no access to the app scheme, and navigation is blocked.

> **Packaging note:** the splash files live under `assets/`, which is also the electron-builder `buildResources` directory. The scaffolded `electron-builder.config.js` includes `assets/**/*` in `files` so the splash ships inside the packaged app (`app.asar`). If you replace the config, keep that entry — otherwise the splash works in development but silently disappears from packaged binaries.

### Debugging

The platform keeps Electron's default application menu, so the Chromium DevTools can be opened at any time via *View → Toggle Developer Tools* or the keyboard shortcut:

| Operating System | Shortcut               |
| ---------------- | ---------------------- |
| macOS            | `Cmd` + `Option` + `I` |
| Windows          | `Ctrl` + `Shift` + `I` |
| Linux            | `Ctrl` + `Shift` + `I` |

To open the DevTools automatically on launch (e.g. to catch logs from early app startup), use the `onWindowCreated` hook in `electron/capacitor.electron.config.ts`:

```
import { defineConfig } from '@capawesome/capacitor-electron/config';

export default defineConfig({
  // ...
  hooks: {
    onWindowCreated: window => {
      window.webContents.openDevTools();
    },
  },
});
```

### Tray Icon

Use the `onWindowCreated` hook together with Electron's [`Tray`](https://www.electronjs.org/docs/latest/api/tray) and [`Menu`](https://www.electronjs.org/docs/latest/api/menu) APIs to add a tray icon and context menu:

```
import { defineConfig } from '@capawesome/capacitor-electron/config';
import { app, Menu, Tray } from 'electron';
import { join } from 'path';

export default defineConfig({
  // ...
  hooks: {
    onWindowCreated: window => {
      const tray = new Tray(join(app.getAppPath(), 'assets', 'tray-icon.png'));
      tray.setContextMenu(
        Menu.buildFromTemplate([
          { label: 'Show', click: () => window.show() },
          { label: 'Hide', click: () => window.hide() },
          { type: 'separator' },
          { label: 'Quit', click: () => app.quit() },
        ]),
      );
    },
  },
});
```

Place the tray icon under `electron/assets/`, which already ships inside the packaged app (see the [Splash Screen](#splash-screen) packaging note). To start the app minimized to the tray, set [`window.showOnLaunch: false`](#configuration) so the main window is created hidden until the user picks *Show*.

> **Migrating from [`@capacitor-community/electron`](https://github.com/capacitor-community/electron)?** This recipe replaces its `trayIconAndMenuEnabled` and `hideMainWindowOnLaunch` options — build the tray via the hook above and use `window.showOnLaunch: false` for start-in-tray behavior.

## Migration

You can use our **AI-Assisted Migration** to migrate from [`@capacitor-community/electron`](https://github.com/capacitor-community/electron). Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-platforms
```

Then use the following prompt:

```
Use the `capacitor-platforms` skill from `capawesome-team/skills` to migrate my project from `@capacitor-community/electron` to `@capawesome/capacitor-electron`.
```

If you prefer **Manual Migration**, perform the following steps:

1. Back up anything you customized in your existing `electron/` directory (icons, electron-builder configuration, and any code you added to the generated runtime files).

1. Remove the old platform and its `electron/` directory:

   ```
   npm uninstall @capacitor-community/electron
   rm -rf electron
   ```

1. Add this platform:

   ```
   npm install @capawesome/capacitor-electron
   npx cap add @capawesome/capacitor-electron
   cd electron && npm install && cd ..
   ```

1. Re-apply your customizations through the typed options in `electron/capacitor.electron.config.ts` (window options, deep-link scheme, CSP overrides, tray/menu via hooks) instead of editing runtime code, and restore your icons to `electron/assets/` and your electron-builder settings in `electron/electron-builder.config.js`.

1. Sync and run (always with the full package name):

   ```
   npx cap sync @capawesome/capacitor-electron
   npx cap run @capawesome/capacitor-electron
   ```

Notes:

- Deep links no longer require hand-written runtime code — declare the scheme in the platform config and listen to `@capacitor/app`'s `appUrlOpen` event.
- Splash screens are picked up automatically from `electron/assets/`. Keep `assets/splash.png` and it just works; if you used a custom `splashScreenImageName: 'x.gif'`, either rename it to `assets/splash.png` or point the config at it via `splashScreen: { path: 'assets/x.gif' }` (see [Splash Screen](#splash-screen)).
- Plugins must provide an electron implementation for this platform's contract (see [Plugin Development](#plugin-development)); implementations written for the old platform are not loaded. Plugins whose web implementation is sufficient continue to work unchanged via the automatic fallback.

## Plugin Development

Plugins declare their electron implementation via `package.json`:

```
{
  "capacitor": {
    "electron": { "src": "electron" }
  }
}
```

`src` is optional and defaults to `electron`, like `android`/`ios` in the Capacitor CLI. The implementation is an ES module at `<src>/dist/plugin.mjs` exporting plugin classes. A plugin class declares its Capacitor registration name and its public API via static metadata — the static property is the contract, so a build-time dependency on this package is not required.

### Recommended: extend `ElectronPlugin`

Mirroring how Android/iOS plugins extend Capacitor's `Plugin` and override `load()`, the recommended path is to extend the `ElectronPlugin` base class. Add `@capawesome/capacitor-electron` as a **devDependency** (for the types) and an **optional peerDependency** (for the runtime value), then:

```
import { ElectronPlugin, defineElectronPlugin } from '@capawesome/capacitor-electron/plugin';

class SqliteImpl extends ElectronPlugin {
  // `this.context` (config, services, notifyListeners) is stored by the base constructor.

  // Optional lifecycle hook. Awaited by the platform before the first window loads.
  async load() { ... }

  async open(options) { ... }
  async query(options) { ... }

  // Not declared below, therefore never bridged.
  resolvePath(path) { ... }
}

export const Sqlite = defineElectronPlugin(
  { name: 'Sqlite', methods: ['open', 'query'] },
  SqliteImpl,
);
```

### Zero-dependency: marker-only

The base class is optional sugar — the discovery contract is the static `__capacitorElectronPlugin` metadata, and the lifecycle hook is detected structurally (never via `instanceof`, which would break across duplicated copies of this package). So a plugin can ship with **no dependency on this package at all**, implementing a structural `load()` if it needs the hook:

```
class SqliteImpl {
  constructor({ config, services, notifyListeners }) { ... }

  // Optional. Structural lifecycle hook, detected by name.
  async load() { ... }

  async open(options) { ... }
  async query(options) { ... }

  // Not declared below, therefore never bridged.
  resolvePath(path) { ... }
}

// Equivalent to defineElectronPlugin, without importing this package.
SqliteImpl.__capacitorElectronPlugin = {
  name: 'Sqlite',
  methods: ['open', 'query'],
};

export { SqliteImpl as Sqlite };
```

The declared `methods` array is the plugin's entire bridged surface: anything not listed stays main-process-internal, and a declared method that is missing on the class fails loudly at boot. Each class is instantiated once in the main process (full Node and Electron API access) and exposed under its registration name through Capacitor's native plugin path — `registerPlugin('Sqlite', { web: ... })` just works, with the web implementation as the automatic fallback for platforms the plugin doesn't cover. No `electron` key in the plugin's `registerPlugin` wiring is needed.

The constructor context (`this.context` on an `ElectronPlugin` subclass, or the constructor argument otherwise) provides:

- `config` — the app's Capacitor configuration.
- `notifyListeners(eventName, data)` — emits a plugin event, mirroring Capacitor's native `notifyListeners`. Web listeners use the standard `addListener(eventName, callback)` / `PluginListenerHandle` API.
- `services` — platform primitives (currently `services.bundles`: switch the served web-bundle directory and reload the app windows).

### The `load()` lifecycle hook

`load()` runs once after the plugin is constructed and is **awaited before the first application window loads**, so async setup — including repointing the active bundle via `services.bundles.setActiveBundle()` — takes effect on first paint (no default-bundle flash). It is a lifecycle hook, **not** a bridged method: `load` is reserved and is never bridged to the renderer. It must **not** be listed in `methods` — doing so is rejected at boot, because bridging it would let web content invoke the lifecycle hook arbitrarily. A rejected or thrown `load()` fails the app boot loudly, the same way a declared-but-missing method does. On an `ElectronPlugin` subclass the default `load()` is a no-op, so overriding it is optional.

At sync time the platform statically scans the app's dependencies and generates a plugin manifest — no plugin code runs outside Electron. Results, thrown `Error`s, and their `code` properties cross the bridge with Capacitor semantics.

## Packaging

The scaffolded `electron/` project packages with electron-builder:

```
cd electron && npm run pack
```

The `pack` script runs three steps: compile (`tsc`), **vendor**, and `electron-builder`. The vendor step (`capacitor-electron vendor`) copies the platform runtime, every plugin's electron implementation, and their dependency closure (production, peer, and installed optional dependencies) into `electron/vendor/`, which the scaffolded electron-builder config maps to `node_modules` inside the packaged app — so module resolution works identically in development (from your app root) and in the package, without a second `npm install` and without version drift.

Code signing, notarization, targets (dmg/msi/nsis/AppImage/deb), and icons are standard electron-builder configuration in the user-owned `electron-builder.config.js` — see https://www.electron.build. Electron Forge is a supported alternative: run `capacitor-electron vendor` before packaging and include `vendor/node_modules` as the app's `node_modules`.

### App Updates

Two independent update layers, matching mobile:

- **Binary updates** (Electron itself, the runtime, native modules): use [electron-updater](https://www.electron.build/auto-update) — the desktop analog of an app-store update. Wire it in your `main.ts`; it operates on the packaged artifacts produced above.
- **Web-bundle updates**: use the [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/) with [Capawesome Cloud](https://capawesome.io/docs/cloud/live-updates/electron/) — download, verification, channels, and failed-boot rollback, exactly like on mobile. The platform itself only ships the serving primitive the plugin builds on: `services.bundles` (`setActiveBundle(dir | null)` switches the served directory in memory and reloads the app windows; `getActiveBundlePath()` returns it). The platform persists nothing and never rolls back; the plugin re-applies its active bundle in its `load()` hook.

## Electron Support Policy

- **Floor**: Electron 28 (required for the runtime's serving APIs). No ceiling — the scaffold uses a caret range you control, and the platform releases only when Electron actually breaks an API it uses.
- **Tested**: CI runs the example app against the latest stable Electron and the floor on every release.
- Electron ships a new major roughly every 8 weeks. This platform's wide peer range means you can adopt new Electron majors immediately, without waiting for a platform release.

## Limitations

Read this before committing to the platform — these are inherent trade-offs, not bugs:

- **Binary size and memory.** Every app ships its own Chromium and Node: expect roughly 80–150 MB installed and a matching memory footprint. If minimal footprint is the priority, Electron is the wrong tool.
- **Plugins need an electron implementation.** Only Capacitor plugins that ship an `electron` implementation (or whose web implementation is sufficient — the automatic fallback) work. iOS/Android native code does not translate.
- **Native Node addons are not rebuilt automatically.** If a plugin's electron implementation depends on native Node modules, `capacitor-electron vendor` detects and reports them, but you must rebuild them against Electron's ABI yourself (e.g. `@electron/rebuild`) before packaging.
- **No web-bundle OTA product included.** The platform provides the serving primitive (`services.bundles`) only; update delivery, channels, and verification are a separate product layer.
- **Always pass the platform name to the Capacitor CLI.** A bare `npx cap sync` only processes iOS/Android/web; `npx cap sync electron` resolves to the `electron` npm package and silently does nothing. Use the full package name (see the note under Installation).
- **Desktop is not mobile.** APIs like geolocation permission prompts, status bars, or app-store review flows have no desktop equivalent; plugins whose web implementation assumes a mobile browser may behave differently on desktop Chromium.

## FAQ

### Can I use any Capacitor plugin with this platform?

Plugins with a dedicated Electron implementation or a sufficient web implementation work. Plugins that only ship iOS/Android native code do not.

### How do I update Electron in my app?

Update the `electron` version in `electron/package.json` and run `npm install` there. The platform supports Electron 28 and later with no upper bound.

### Does `Capacitor.getPlatform()` return `electron`?

Yes. `Capacitor.getPlatform()` returns `'electron'` and `Capacitor.isNativePlatform()` returns `true`, so you can branch platform-specific code the same way as on iOS and Android.

### Can I use Live Updates on Electron?

Yes. The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/) (8.5.0 or later) has a native Electron implementation and uses the same Capawesome Cloud app as your mobile app. See [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/).

## Related Plugins

- [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/) — over-the-air web-bundle updates with Capawesome Cloud, with a native Electron implementation.
- [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/) — local SQL database with a native Electron implementation.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-electron/blob/main/BREAKING.md).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-electron/blob/main/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-electron/blob/main/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by the OpenJS Foundation or any of its affiliates. `Electron` is a trademark of the OpenJS Foundation. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Exif Plugin

Capacitor plugin to read, write and remove EXIF metadata from image files.

## Features

- 📖 **Read**: Read typed EXIF tags like GPS position, camera model, and capture date.
- ✍️ **Write**: Update EXIF tags in place without touching the rest of the file.
- 🕵️ **Privacy**: Strip GPS positions and other sensitive metadata before uploading images.
- 💎 **Lossless**: The pixel data is never re-encoded, so the image quality is not affected.
- 🖼️ **HEIC support**: Read and write HEIC metadata natively, which JavaScript libraries can not do.
- ⚡ **Native performance**: Files are processed natively and never loaded into the WebView memory.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/), [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) and [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Exif plugin is typically used whenever an app needs to work with photo metadata, for example:

- **Privacy protection**: Strip GPS positions and other sensitive metadata from photos before uploading them to a server.
- **Photo organization**: Read the capture date and GPS position to sort and group photos.
- **Metadata correction**: Fix a wrong capture date or add a missing GPS position without re-encoding the image.
- **Camera details**: Display camera and lens information such as ISO, aperture, and exposure time in a photo detail view.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [How to Take and Edit Photos in a Capacitor App](https://capawesome.io/blog/how-to-take-and-edit-photos-in-a-capacitor-app/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-exif` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-exif
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$androidxExifInterfaceVersion` version of `androidx.exifinterface:exifinterface` (default: `1.4.2`)

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read the EXIF metadata of an image, write EXIF tags to an image, and remove the EXIF metadata from an image.

### Read the EXIF metadata of an image

Read typed EXIF tags such as the GPS position, camera model, and capture date from an image file. Only available on Android and iOS:

```
import { Exif } from '@capawesome/capacitor-exif';

const readExif = async () => {
  const { tags } = await Exif.readExif({
    path: 'file:///path/to/photo.jpg',
  });
  console.log('GPS position:', tags.gpsLatitude, tags.gpsLongitude);
};
```

### Write EXIF tags to an image

Update EXIF tags in place. Only the provided tags are updated and the pixel data is never re-encoded. Only available on Android and iOS:

```
import { Exif } from '@capawesome/capacitor-exif';

const writeExif = async () => {
  await Exif.writeExif({
    path: 'file:///path/to/photo.jpg',
    tags: {
      dateTimeOriginal: '2026:01:15 10:30:00',
      gpsLatitude: 51.503364,
      gpsLongitude: -0.127625,
    },
  });
};
```

### Remove the EXIF metadata from an image

Strip all EXIF metadata from an image file in place, for example to protect the privacy of your users before an upload. By default, the orientation tag is kept so that the image is not suddenly displayed rotated. Only available on Android and iOS:

```
import { Exif } from '@capawesome/capacitor-exif';

const removeExif = async () => {
  await Exif.removeExif({
    path: 'file:///path/to/photo.jpg',
  });
};
```

## API

- [`readExif(...)`](#readexif)
- [`removeExif(...)`](#removeexif)
- [`writeExif(...)`](#writeexif)
- [Interfaces](#interfaces)

### readExif(...)

```
readExif(options: ReadExifOptions) => Promise<ReadExifResult>
```

Read the EXIF metadata of an image file.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `ReadExifOptions` |

**Returns:** `Promise<ReadExifResult>`

**Since:** 0.1.0

______________________________________________________________________

### removeExif(...)

```
removeExif(options: RemoveExifOptions) => Promise<void>
```

Remove the EXIF metadata from an image file in place.

The pixel data is never re-encoded, so the image quality is not affected.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `RemoveExifOptions` |

**Since:** 0.1.0

______________________________________________________________________

### writeExif(...)

```
writeExif(options: WriteExifOptions) => Promise<void>
```

Write EXIF metadata to an image file in place.

Only the provided tags are updated. All other tags remain unchanged. The pixel data is never re-encoded, so the image quality is not affected.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `WriteExifOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ReadExifResult

| Prop       | Type       | Description                                       | Since |
| ---------- | ---------- | ------------------------------------------------- | ----- |
| **`tags`** | `ExifTags` | The EXIF tags that were read from the image file. | 0.1.0 |

#### ExifTags

The EXIF tags of an image file.

Every property is optional and only present if the tag exists in the file.

| Prop                   | Type      | Description                                                                                                        | Since |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
| **`dateTimeOriginal`** | `string`  | The date and time when the image was originally captured in the EXIF date format `YYYY:MM:DD HH:MM:SS`.            | 0.1.0 |
| **`exposureTime`**     | `number`  | The exposure time in seconds.                                                                                      | 0.1.0 |
| **`fNumber`**          | `number`  | The F number (aperture) of the lens.                                                                               | 0.1.0 |
| **`flash`**            | `boolean` | Whether or not the flash fired when the image was captured.                                                        | 0.1.0 |
| **`focalLength`**      | `number`  | The focal length of the lens in millimeters.                                                                       | 0.1.0 |
| **`gpsAltitude`**      | `number`  | The altitude in meters above (positive) or below (negative) sea level.                                             | 0.1.0 |
| **`gpsLatitude`**      | `number`  | The latitude in signed decimal degrees. Positive values are north of the equator, negative values are south.       | 0.1.0 |
| **`gpsLongitude`**     | `number`  | The longitude in signed decimal degrees. Positive values are east of the prime meridian, negative values are west. | 0.1.0 |
| **`iso`**              | `number`  | The ISO speed rating (photographic sensitivity).                                                                   | 0.1.0 |
| **`lensModel`**        | `string`  | The model of the lens.                                                                                             | 0.1.0 |
| **`make`**             | `string`  | The manufacturer of the camera.                                                                                    | 0.1.0 |
| **`model`**            | `string`  | The model of the camera.                                                                                           | 0.1.0 |
| **`orientation`**      | `number`  | The orientation of the image as defined by the EXIF specification (1-8).                                           | 0.1.0 |
| **`pixelHeight`**      | `number`  | The height of the image in pixels.                                                                                 | 0.1.0 |
| **`pixelWidth`**       | `number`  | The width of the image in pixels.                                                                                  | 0.1.0 |
| **`software`**         | `string`  | The name of the software that was used to create or edit the image.                                                | 0.1.0 |

#### ReadExifOptions

| Prop       | Type     | Description                                                                                                   | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path to the image file to read the EXIF metadata from. Local file paths and `file://` URIs are supported. | 0.1.0 |

#### RemoveExifOptions

| Prop                  | Type      | Description                                                                                                                                                                                   | Default | Since |
| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`keepOrientation`** | `boolean` | Whether or not to keep the orientation tag when removing the EXIF metadata. This is enabled by default so that images are not suddenly displayed rotated after the metadata has been removed. | `true`  | 0.1.0 |
| **`path`**            | `string`  | The path to the image file to remove the EXIF metadata from. Local file paths and `file://` URIs are supported.                                                                               |         | 0.1.0 |

#### WriteExifOptions

| Prop       | Type               | Description                                                                                                    | Since |
| ---------- | ------------------ | -------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string`           | The path to the image file to write the EXIF metadata to. Local file paths and `file://` URIs are supported.   | 0.1.0 |
| **`tags`** | `WritableExifTags` | The EXIF tags to write to the image file. Only the provided tags are updated. All other tags remain unchanged. | 0.1.0 |

#### WritableExifTags

The writable subset of the EXIF tags.

| Prop                   | Type      | Description                                                                                                                                                      | Since |
| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`dateTimeOriginal`** | `string`  | The date and time when the image was originally captured in the EXIF date format `YYYY:MM:DD HH:MM:SS`.                                                          | 0.1.0 |
| **`exposureTime`**     | `number`  | The exposure time in seconds.                                                                                                                                    | 0.1.0 |
| **`fNumber`**          | `number`  | The F number (aperture) of the lens.                                                                                                                             | 0.1.0 |
| **`flash`**            | `boolean` | Whether or not the flash fired when the image was captured.                                                                                                      | 0.1.0 |
| **`focalLength`**      | `number`  | The focal length of the lens in millimeters.                                                                                                                     | 0.1.0 |
| **`gpsAltitude`**      | `number`  | The altitude in meters above (positive) or below (negative) sea level.                                                                                           | 0.1.0 |
| **`gpsLatitude`**      | `number`  | The latitude in signed decimal degrees. Positive values are north of the equator, negative values are south. Must be provided together with `gpsLongitude`.      | 0.1.0 |
| **`gpsLongitude`**     | `number`  | The longitude in signed decimal degrees. Positive values are east of the prime meridian, negative values are west. Must be provided together with `gpsLatitude`. | 0.1.0 |
| **`iso`**              | `number`  | The ISO speed rating (photographic sensitivity).                                                                                                                 | 0.1.0 |
| **`lensModel`**        | `string`  | The model of the lens.                                                                                                                                           | 0.1.0 |
| **`make`**             | `string`  | The manufacturer of the camera.                                                                                                                                  | 0.1.0 |
| **`model`**            | `string`  | The model of the camera.                                                                                                                                         | 0.1.0 |
| **`orientation`**      | `number`  | The orientation of the image as defined by the EXIF specification (1-8).                                                                                         | 0.1.0 |
| **`software`**         | `string`  | The name of the software that was used to create or edit the image.                                                                                              | 0.1.0 |

## Format Support

The plugin can read EXIF metadata from any image format that the platform supports. Writing and removing EXIF metadata is a lossless in-place operation that is only supported for the following formats:

| Format    | Read (Android) | Read (iOS) | Write & Remove (Android) | Write & Remove (iOS) |
| --------- | -------------- | ---------- | ------------------------ | -------------------- |
| JPEG      | ✅             | ✅         | ✅                       | ✅                   |
| PNG       | ✅             | ✅         | ✅                       | ❌                   |
| WebP      | ✅             | ✅         | ✅                       | ❌                   |
| HEIC/HEIF | ✅             | ✅         | ❌                       | ✅                   |
| DNG/RAW   | ✅             | ✅         | ❌                       | ❌                   |

Calling `writeExif(...)` or `removeExif(...)` with an unsupported format rejects with the `UNSUPPORTED_FORMAT` error code.

## Lossless Metadata Writes

A metadata plugin that degrades the image quality is broken. This plugin therefore guarantees that the pixel data is never decoded or re-encoded:

- On **Android**, the [`ExifInterface`](https://developer.android.com/reference/androidx/exifinterface/media/ExifInterface) library rewrites only the metadata segments of the file in place.
- On **iOS**, the [`CGImageDestinationCopyImageSource`](<https://developer.apple.com/documentation/imageio/cgimagedestinationcopyimagesource(_:_:_:_:)>) API copies the compressed image data unchanged and only replaces the metadata.

## Privacy: Strip Metadata Before Upload

Images taken with a smartphone usually contain the exact GPS position, the device model, and the capture date. To protect the privacy of your users, remove this metadata before uploading images to a server:

```
import { Exif } from '@capawesome/capacitor-exif';

const prepareUpload = async (path: string) => {
  // Remove the GPS position and all other EXIF metadata.
  // The orientation is kept so that the image is not displayed rotated.
  await Exif.removeExif({ path });
};
```

## Limitations

### Android

- Vendor-specific maker notes and other unknown tags may survive `removeExif(...)` since the `ExifInterface` library can only remove known tags.

### iOS

- HEIC files store the orientation at the container level, so the `orientation` tag can not be changed and is always kept, even with `keepOrientation` set to `false`.
- HEIC files may keep the `software` and `dateTimeOriginal` tags after `removeExif(...)`. GPS data and device identity tags (`make`, `model`, `lensModel`) are always removed.

## FAQ

### How is this plugin different from other similar plugins?

It reads, writes and removes EXIF metadata directly on the image file on Android and iOS, updating tags in place so the pixel data is never re-encoded and the image quality is untouched. It reads and writes HEIC metadata natively, processes files natively without loading them into WebView memory, and uses only official platform APIs, so it stays App Store safe. The API is fully typed, ships for both CocoaPods and Swift Package Manager, and is kept current with the latest Capacitor version.

### Which platforms are supported by this plugin?

The plugin supports Android and iOS. All methods (`readExif`, `writeExif` and `removeExif`) are only available on these two platforms, since the files are processed natively and never loaded into the WebView memory.

### Does writing or removing EXIF metadata affect the image quality?

No. Writing and removing EXIF metadata is a lossless in-place operation. The pixel data is never decoded or re-encoded, so the image quality is not affected. See [Lossless Metadata Writes](#lossless-metadata-writes) for details on how this is implemented on each platform.

### Which image formats are supported?

Reading EXIF metadata works with any image format that the platform supports, including JPEG, PNG, WebP, HEIC/HEIF, and DNG/RAW. Writing and removing metadata is only supported for certain formats, which differ between Android and iOS (see [Format Support](#format-support)). Calling `writeExif(...)` or `removeExif(...)` with an unsupported format rejects with the `UNSUPPORTED_FORMAT` error code.

### Why is the orientation tag still present after calling `removeExif`?

The `keepOrientation` option is enabled by default so that images are not suddenly displayed rotated after the metadata has been removed. You can set it to `false` to also remove the orientation tag. Note that HEIC files on iOS store the orientation at the container level, so it is always kept there.

### How do I remove the GPS position from a photo before uploading it?

Call `removeExif(...)` with the path to the image file. This strips the GPS position along with all other EXIF metadata in place, without affecting the image quality. See [Privacy: Strip Metadata Before Upload](#privacy-strip-metadata-before-upload) for an example.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress images in formats like PNG, JPEG, and WebP.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Pick the image files whose metadata you want to read or edit.
- [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/): Let the user edit a photo.
- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/): Headless image transforms like crop, resize, rotate, and format conversion.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/exif/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/exif/LICENSE).

# Capacitor Facebook Sign-In Plugin

Unofficial Capacitor plugin to sign-in with Facebook.[1](#fn:1)

## Features

The Capacitor Facebook Sign-In plugin is a comprehensive Facebook authentication solution for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🔐 **Authentication**: Sign in users with their Facebook account.
- 🔑 **Access Token**: Retrieve the access token for the Facebook Graph API.
- 👤 **User Profile**: Retrieve the user's email, display name, profile picture, and more.
- 🕵️ **Limited Login**: Support for Limited Login on iOS to sign in users without tracking.
- 🛡️ **Nonce Support**: Prevent replay attacks with a custom nonce on iOS.
- 🪶 **Lightweight**: Just a single dependency and zero unnecessary bloat.
- 🚨 **Error Codes**: Provides detailed error codes for better error handling.
- 🤝 **Compatibility**: Works alongside the [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/) and [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Facebook Sign-In plugin is typically used wherever users should sign in with their existing Facebook account, for example:

- **Social login**: Let users sign in to your app with their Facebook account instead of creating a new password.
- **Backend authentication**: Send the authentication token (JWT) to your backend to verify the user's identity.
- **Graph API access**: Use the access token to request data from the Facebook Graph API on behalf of the user.
- **Privacy-friendly sign-in on iOS**: Use Limited Login to sign in users without tracking and without App Tracking Transparency consent.
- **Profile pre-filling**: Use the user's email, display name, and profile picture to pre-fill their profile in your app.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-facebook-sign-in` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-facebook-sign-in
npx cap sync
```

This plugin requires a Facebook app. If you don't have one yet, create it in the [Meta App Dashboard](https://developers.facebook.com/apps/) and add the **Facebook Login** product. You can find your **App ID** and **Client Token** in the app settings.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$facebookLoginVersion` version of `com.facebook.android:facebook-login` (default: `18.3.0`)

#### Resources

Add the following string resources to the `android/app/src/main/res/values/strings.xml` file:

```
<string name="facebook_app_id">YOUR_APP_ID</string>
<string name="facebook_client_token">YOUR_CLIENT_TOKEN</string>
```

Replace `YOUR_APP_ID` with your Facebook App ID and `YOUR_CLIENT_TOKEN` with your Facebook Client Token.

#### Metadata

Add the following elements inside the `application` tag of the `android/app/src/main/AndroidManifest.xml` file:

```
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />
<meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token" />
```

### iOS

Add the following keys to the `ios/App/App/Info.plist` file:

```
<key>FacebookAppID</key>
<string>YOUR_APP_ID</string>
<key>FacebookClientToken</key>
<string>YOUR_CLIENT_TOKEN</string>
<key>FacebookDisplayName</key>
<string>YOUR_APP_NAME</string>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>fbapi</string>
  <string>fb-messenger-share-api</string>
</array>
```

Replace `YOUR_APP_ID` with your Facebook App ID, `YOUR_CLIENT_TOKEN` with your Facebook Client Token, and `YOUR_APP_NAME` with the display name of your Facebook app.

You also need to add the URL scheme for your Facebook App ID to the `ios/App/App/Info.plist` file:

```
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fbYOUR_APP_ID</string>
    </array>
  </dict>
</array>
```

Replace `YOUR_APP_ID` with your Facebook App ID, so that the URL scheme is your App ID prefixed with `fb` (e.g. `fb1234567890123456`).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize the plugin, sign in a user, sign in with Limited Login, get the current access token, and sign out a user.

### Initialize the plugin

Call `initialize(...)` once before all other methods. On Android and iOS, the App ID is usually read from the native configuration, so the `appId` option is only required on Web:

```
import { FacebookSignIn } from '@capawesome/capacitor-facebook-sign-in';

const initialize = async () => {
  await FacebookSignIn.initialize({
    appId: '1234567890123456',
  });
};
```

### Sign in a user

Start the Facebook Sign-In flow and retrieve the access token and the user's profile:

```
import { FacebookSignIn } from '@capawesome/capacitor-facebook-sign-in';

const signIn = async () => {
  const result = await FacebookSignIn.signIn();
  console.log(result.accessToken?.token);
  console.log(result.profile.id);
  console.log(result.profile.name);
  console.log(result.profile.email);
};
```

### Sign in with Limited Login

Use Limited Login to sign in users without tracking. Instead of an access token, an authentication token (JWT) is returned that can be verified on your backend. Provide a nonce to prevent replay attacks. Only available on iOS:

```
import { FacebookSignIn } from '@capawesome/capacitor-facebook-sign-in';

const signInWithLimitedLogin = async () => {
  const result = await FacebookSignIn.signIn({
    limitedLogin: true,
    nonce: 'YOUR_NONCE',
  });
  console.log(result.authenticationToken);
};
```

### Get the current access token

Retrieve the current access token, for example to check whether a user is still signed in. The result is `null` if no user is signed in or the access token has expired:

```
import { FacebookSignIn } from '@capawesome/capacitor-facebook-sign-in';

const getCurrentAccessToken = async () => {
  const { accessToken } = await FacebookSignIn.getCurrentAccessToken();
  console.log(accessToken?.token);
};
```

### Sign out a user

Sign out the current user:

```
import { FacebookSignIn } from '@capawesome/capacitor-facebook-sign-in';

const signOut = async () => {
  await FacebookSignIn.signOut();
};
```

## API

- [`getCurrentAccessToken()`](#getcurrentaccesstoken)
- [`initialize(...)`](#initialize)
- [`signIn(...)`](#signin)
- [`signOut()`](#signout)
- [Interfaces](#interfaces)

### getCurrentAccessToken()

```
getCurrentAccessToken() => Promise<GetCurrentAccessTokenResult>
```

Get the current access token.

**Returns:** `Promise<GetCurrentAccessTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

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

Initialize the Facebook Sign-In plugin.

This method must be called once before all other methods.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### signIn(...)

```
signIn(options?: SignInOptions | undefined) => Promise<SignInResult>
```

Start the Facebook Sign-In flow.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `SignInOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signOut()

```
signOut() => Promise<void>
```

Sign out the current user.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetCurrentAccessTokenResult

| Prop              | Type          | Description | Since                                                                                             |
| ----------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| **`accessToken`** | \`AccessToken | null\`      | The current access token. This is `null` if no user is signed in or the access token has expired. |

#### AccessToken

| Prop              | Type       | Description                                                                         | Since |
| ----------------- | ---------- | ----------------------------------------------------------------------------------- | ----- |
| **`expiresAt`**   | `number`   | The timestamp (in milliseconds since the Unix epoch) when the access token expires. | 0.1.0 |
| **`permissions`** | `string[]` | The permissions granted to the access token.                                        | 0.1.0 |
| **`token`**       | `string`   | The access token string.                                                            | 0.1.0 |
| **`userId`**      | `string`   | The unique identifier of the user's Facebook account.                               | 0.1.0 |

#### InitializeOptions

| Prop              | Type     | Description                                                                                                                                                                                           | Since |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`appId`**       | `string` | The Facebook App ID from the Meta App Dashboard. On Android and iOS, this overrides the value from the native configuration and is usually not needed. **Attention**: This option is required on Web. | 0.1.0 |
| **`clientToken`** | `string` | The Facebook Client Token from the Meta App Dashboard. This overrides the value from the native configuration and is usually not needed. Only available on Android and iOS.                           | 0.1.0 |

#### SignInResult

| Prop                      | Type          | Description                        | Since                                                                                                                                            |
| ------------------------- | ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`accessToken`**         | \`AccessToken | null\`                             | The access token for accessing the Facebook Graph API. This is `null` on iOS when Limited Login is used.                                         |
| **`authenticationToken`** | \`string      | null\`                             | The authentication token (JWT) returned by Facebook. This token can be sent to your backend for verification. Only available on Android and iOS. |
| **`profile`**             | `Profile`     | The profile of the signed-in user. | 0.1.0                                                                                                                                            |

#### Profile

| Prop           | Type     | Description                                           | Since                                                                               |
| -------------- | -------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **`email`**    | \`string | null\`                                                | The user's email address. This is `null` if the `email` permission was not granted. |
| **`id`**       | `string` | The unique identifier of the user's Facebook account. | 0.1.0                                                                               |
| **`imageUrl`** | \`string | null\`                                                | The URL of the user's profile picture.                                              |
| **`name`**     | \`string | null\`                                                | The user's display name (full name).                                                |

#### SignInOptions

| Prop               | Type       | Description                                                                                                                                                                                                                                                                                          | Default                       | Since |
| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- |
| **`limitedLogin`** | `boolean`  | Whether or not to use [Limited Login](https://developers.facebook.com/docs/facebook-login/limited-login/) instead of classic login. With Limited Login, no access token is returned. Instead, an authentication token (JWT) is returned that can be verified on your backend. Only available on iOS. | `false`                       | 0.1.0 |
| **`nonce`**        | `string`   | A nonce to prevent replay attacks. The nonce is included in the authentication token and can be verified on your backend. Only available on iOS.                                                                                                                                                     |                               | 0.1.0 |
| **`permissions`**  | `string[]` | The permissions to request from the user.                                                                                                                                                                                                                                                            | `["public_profile", "email"]` | 0.1.0 |

## Limited Login

On iOS, the Facebook SDK distinguishes between classic login and [Limited Login](https://developers.facebook.com/docs/facebook-login/limited-login/). With Limited Login, no data is shared with Meta that could be used for tracking, so no App Tracking Transparency consent is required. However, no access token for the Facebook Graph API is returned. Instead, an authentication token (JWT) is returned, which can be verified on your backend.

Keep the following in mind:

- Set the `limitedLogin` option to `true` to use Limited Login.
- If the user has not granted the App Tracking Transparency permission, the Facebook SDK may fall back to Limited Login even if classic login was requested. In this case, the `accessToken` property in the sign-in result is `null`.
- Provide a `nonce` option and verify it on your backend to prevent replay attacks.

## Security

This plugin handles the sign-in flow and returns tokens to your app. To keep your integration secure, be aware of the following:

- **Server-side token verification is required.** The `authenticationToken` (JWT) is **not** verified client-side. Your backend **must** verify the JWT signature using [Facebook's public keys](https://www.facebook.com/.well-known/oauth/openid/jwks/) before trusting any claims. Never use client-side token data for authorization decisions without server-side verification.
- **Validate the access token on your backend.** If you use the `accessToken`, your backend should validate it with the [Facebook Graph API](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow#checktoken) before trusting it.

## FAQ

### How is this plugin different from other similar plugins?

It covers the full Facebook sign-in flow across Android, iOS, and the Web, returning both the access token for the Graph API and the signed-in user's profile through a fully typed API. On iOS it supports Limited Login with nonce verification, so you can sign users in without tracking and without App Tracking Transparency consent, and it works alongside the Apple and Google Sign-In plugins when you want to offer several options. Detailed error codes and support for the latest Capacitor version round it out. If you only ever need a single provider, a lighter setup can be enough; when you need Facebook handled thoroughly, this plugin is built for exactly that.

### Do I need a Facebook app to use this plugin?

Yes, this plugin requires a Facebook app. You can create one in the [Meta App Dashboard](https://developers.facebook.com/apps/) and add the **Facebook Login** product to it. The **App ID** and **Client Token** from the app settings are needed for the platform-specific configuration, see the [Installation](#installation) section.

### What is Limited Login and when should I use it?

Limited Login is an alternative sign-in mode of the Facebook SDK on iOS. With Limited Login, no data is shared with Meta that could be used for tracking, so no App Tracking Transparency consent is required. However, no access token for the Facebook Graph API is returned. Instead, an authentication token (JWT) is returned, which can be verified on your backend. Set the `limitedLogin` option to `true` to use it.

### Why is the `accessToken` property `null` after signing in on iOS?

This happens when Limited Login is used. If the user has not granted the App Tracking Transparency permission, the Facebook SDK may fall back to Limited Login even if classic login was requested. In this case, use the `authenticationToken` (JWT) instead and verify it on your backend.

### How do I verify the sign-in on my backend?

Your backend must verify the JWT signature of the `authenticationToken` using [Facebook's public keys](https://www.facebook.com/.well-known/oauth/openid/jwks/) before trusting any claims. If you use the `accessToken`, your backend should validate it with the Facebook Graph API before trusting it. See the [Security](#security) section for more details.

### Can I use this plugin together with other sign-in plugins?

Yes, the plugin works alongside the [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/) and [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/) plugins, so you can offer multiple sign-in options in the same app.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/): Sign in users with their Apple account.
- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication such as face or fingerprint recognition.
- [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/): Sign in users with their Google account.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with any OAuth 2.0 and OpenID Connect provider.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/facebook-sign-in/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/facebook-sign-in/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Meta Platforms, Inc. or any of its affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor File Compressor Plugin

Capacitor plugin for efficient file compression with support for image formats like PNG, JPEG, and WebP.

## Features

The Capacitor File Compressor plugin offers one of the most complete file compression solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🌅 **Compress Images**: Compress png, jpeg, and webp images.
- 🤝 **Compatibility**: Compatible with the [Zip](https://capawesome.io/docs/sdks/capacitor/zip/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The File Compressor plugin is typically used to shrink images before they leave the device, for example:

- **Image uploads**: Compress photos before uploading them to a server to save bandwidth and speed up uploads.
- **Storage savings**: Reduce the size of images before storing them on the device or in the cloud.
- **Thumbnails and previews**: Use the `width` and `height` options to create smaller versions of images for lists and galleries.
- **Format conversion**: Convert PNG images to smaller JPEG or WebP files using the `mimeType` option.

## 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     |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-plugin-demo).

| Android |
| ------- |
|         |

## Guides

- [Exploring the Capacitor File Compressor API](https://capawesome.io/blog/exploring-the-capacitor-file-compressor-api/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-compressor` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-file-compressor
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$androidxDocumentFileVersion` version of `androidx.documentfile:documentfile` (default: `1.1.0`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to compress an image while controlling its quality and dimensions.

### Compress an image

Compress a PNG, JPEG, or WebP image by passing its path (Android and iOS) or blob (Web). Use the `quality` option to control the compression level and the optional `width` and `height` options to resize the image:

```
import { FileCompressor } from '@capawesome-team/capacitor-file-compressor';

const compressImage = async () => {
  const { path } = await FileCompressor.compressImage({
    height: 1000,
    mimeType: 'image/jpeg',
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000485',
    quality: 0.7,
    width: 1000,
  });
  return path;
};
```

## API

- [`compressImage(...)`](#compressimage)
- [Interfaces](#interfaces)

### compressImage(...)

```
compressImage(options: CompressImageOptions) => Promise<CompressImageResult>
```

Compress an image.

Only png, jpeg, and webp images are supported.

**Attention**: The exif data of the image is lost during compression.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `CompressImageOptions` |

**Returns:** `Promise<CompressImageResult>`

**Since:** 5.0.0

______________________________________________________________________

### Interfaces

#### CompressImageResult

| Prop       | Type     | Description                                                         | Since |
| ---------- | -------- | ------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path of the compressed file. Only available on Android and iOS. | 5.0.0 |
| **`blob`** | `Blob`   | The blob of the compressed file. Only available on Web.             | 5.0.0 |

#### CompressImageOptions

| Prop           | Type     | Description                                                                                                                                                                                                                    | Default        | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ----- |
| **`blob`**     | `Blob`   | The blob of the file to compress. Only available on Web.                                                                                                                                                                       |                | 5.0.0 |
| **`height`**   | `number` | The height of the resulting image.                                                                                                                                                                                             |                | 7.1.0 |
| **`mimeType`** | `string` | The mime type of the compressed file. On Android, only `image/jpeg` and `image/webp` are supported. On iOS, only `image/jpeg` is supported. On Web, only `image/jpeg` and `image/webp` are supported.                          | `'image/jpeg'` | 5.0.0 |
| **`path`**     | `string` | The path of the file to compress. Only available on Android and iOS.                                                                                                                                                           |                | 5.0.0 |
| **`quality`**  | `number` | The quality of the resulting image, expressed as a value from `0.0` to `1.0`. The value `0.0` represents the maximum compression (or lowest quality) while the value `1.0` represents the least compression (or best quality). | `0.6`          | 5.0.0 |
| **`width`**    | `number` | The width of the resulting image.                                                                                                                                                                                              |                | 7.1.0 |

## FAQ

### Which image formats are supported?

The plugin can compress PNG, JPEG, and WebP images. The output format is controlled by the `mimeType` option: on Android and Web, `image/jpeg` and `image/webp` are supported, while on iOS only `image/jpeg` is supported. The default output format is `image/jpeg`.

### How do I control the compression quality?

Use the `quality` option, which accepts a value from `0.0` to `1.0`. The value `0.0` represents the maximum compression (or lowest quality) while `1.0` represents the least compression (or best quality). The default is `0.6`. You can additionally resize the image with the `width` and `height` options to reduce the file size even further.

### Does the plugin preserve EXIF metadata?

No, the EXIF data of the image is lost during compression. If you need the metadata, read it before compressing the image and store it separately.

### What does `compressImage` return on each platform?

On Android and iOS, the result contains the `path` of the compressed file. On Web, the result contains a `Blob` instance instead. Take this into account if you share code across platforms, for example when uploading the compressed image to a server.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select the images to compress from the file system or gallery.
- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/): Headless image transforms like crop, resize, rotate, flip and format conversion.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Zip and unzip files and directories with support for encryption.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-compressor/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-compressor/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-compressor/LICENSE).

# Capacitor File Manager Plugin

Capacitor plugin to manage files and directories on Android, iOS and Web. Persist access to user-picked folders, run copy, move and delete operations with progress and cancellation, calculate checksums, and inspect device and app storage.

## Features

The Capacitor File Manager plugin works with the user's own storage, not just your app's sandbox. Here are some of the key features:

- 📂 **Persistent Directory Access**: Let the user pick a folder once with the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugin and keep read and write access to it across app launches — Play-policy-compliant on Android, sandbox-correct on iOS.
- 🔗 **URI-based API**: Every method works directly with file URIs. Construct them with `getUri(...)` from well-known directories or any parent URI.
- 📄 **Files**: Read, write, append, truncate, copy, move and delete files with constant memory usage, including random access reads and writes for large files.
- 🗂️ **Directories**: Create, read, copy, move, delete and clear directories, and calculate their total size — with rich metadata and paging.
- 📊 **Progress & Cancellation**: Directory operations report progress events and can be canceled at any time.
- 🔢 **Checksums**: Calculate MD5, SHA-1 and SHA-256 checksums of files of any size with constant memory usage.
- 🧲 **Blob Reads**: Read large files as a `Blob` without base64 overhead via `readFileAsBlob(...)`.
- 💾 **Storage Info**: Query the total and free storage space of the device, the storage usage of your app, and clear the app's cache.
- 🌐 **Web Support**: A real web implementation on top of the Origin Private File System with actual directories, streaming and random access — not base64 blobs in IndexedDB.
- ⚠️ **Error Codes**: Every runtime failure rejects with a documented error code, so you can branch on it instead of parsing messages.
- 🤝 **Compatibility**: Works hand in hand with the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Transfer](https://capawesome.io/docs/sdks/capacitor/file-transfer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The File Manager plugin is typically used whenever an app needs durable access to user-picked folders or manager-grade file operations, for example:

- **Document management apps**: Let the user pick a folder once and organize, rename and sort documents in it across app launches.
- **Download and media managers**: Check the free storage space before a download, verify the result with a checksum, and move it into a user-visible folder.
- **Backup and export**: Export app data into a folder the user picked, with progress reporting and cancellation for large exports.
- **Large file processing**: Read file headers with random access, stream large files into your web code as a `Blob`, and truncate or append without rewriting the whole file.
- **Cache management**: Show the user how much space your app occupies and offer a one-tap cache cleanup.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [Announcing the Capacitor File Manager Plugin](https://capawesome.io/blog/announcing-the-capacitor-file-manager-plugin/): What this plugin adds on top of `@capacitor/filesystem`: persisted folder access, directory operations with progress and cancellation, checksums, and a web implementation on the Origin Private File System.
- [Android Scoped Storage in Capacitor Apps, Explained](https://capawesome.io/blog/android-scoped-storage-in-capacitor-apps/): Which directories still work without permissions, and how this plugin wraps the Storage Access Framework in persisted folder access.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-manager` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-file-manager
npx cap sync
```

### Android

This plugin requires no storage permissions. The app's sandbox directories are accessible without any permission, and user-visible folders are accessed through persisted directories, which are granted by the user in the system file picker.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### Web

On the web platform, files are stored in the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Persisted directories and checksums are not available on the web.

#### Data persistence

The Origin Private File System is subject to the browser's storage eviction rules. By default, storage is granted on a best-effort basis: Chromium-based browsers and Firefox only evict data under storage pressure, but Safari deletes all script-writable storage after seven days without user interaction if the app runs in a browser tab. Web apps added to the home screen are exempt from this rule.

To reduce the risk of eviction, request persistent storage with [`navigator.storage.persist()`](https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist) at a moment of meaningful user engagement (for example, after sign-in or after the user has saved data for the first time). Note that persistence is granted at the browser's discretion and reduces the risk of eviction, but is not an absolute guarantee.

## Configuration

No configuration required for this plugin.

## Usage

### Write and read a file in the app's sandbox

```
import { Directory, Encoding, FileManager } from '@capawesome-team/capacitor-file-manager';

const writeAndReadFile = async () => {
  const { uri } = await FileManager.getUri({
    path: 'notes/todo.txt',
    directory: Directory.Data,
  });
  await FileManager.writeFile({
    uri,
    data: 'Hello, World!',
    encoding: Encoding.Utf8,
    recursive: true,
  });
  const { data } = await FileManager.readFile({ uri, encoding: Encoding.Utf8 });
  return data;
};
```

### Persist access to a picked directory

This requires version `8.1.0` or later of the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugin, since `pickDirectory()` only returns a bookmark from that version on.

```
import { FileManager } from '@capawesome-team/capacitor-file-manager';
import { FilePicker } from '@capawesome/capacitor-file-picker';

const persistDirectoryAccess = async () => {
  const result = await FilePicker.pickDirectory();
  const { directory } = await FileManager.persistDirectoryAccess({
    uri: result.path,
    bookmark: result.bookmark,
  });
  return directory;
};

const getPersistedDirectories = async () => {
  // Call this on app start and use the returned URIs
  // instead of storing them yourself.
  const { directories } = await FileManager.getPersistedDirectories();
  return directories;
};
```

### Work inside a persisted directory

```
import { Directory, FileManager } from '@capawesome-team/capacitor-file-manager';

const exportIntoPickedDirectory = async (directoryUri: string) => {
  // Construct the URI of a file inside the picked directory.
  const { uri: targetUri } = await FileManager.getUri({
    path: 'exports/report.pdf',
    parentUri: directoryUri,
  });
  // Copy a file from the app's sandbox into the picked directory.
  const { uri: sourceUri } = await FileManager.getUri({
    path: 'report.pdf',
    directory: Directory.Cache,
  });
  const { uri } = await FileManager.copyFile({ uri: sourceUri, toUri: targetUri });
  return uri;
};

const listPickedDirectory = async (directoryUri: string) => {
  const { entries } = await FileManager.readDirectory({ uri: directoryUri });
  return entries;
};
```

### Copy a directory with progress and cancellation

```
import { FileManager } from '@capawesome-team/capacitor-file-manager';

const copyDirectoryWithProgress = async (uri: string, toUri: string) => {
  await FileManager.addListener('operationProgress', (event) => {
    console.log(`Processed ${event.processedFiles} of ${event.totalFiles} files`);
  });
  await FileManager.copyDirectory({ uri, toUri, id: 'my-copy-operation' });
};

const cancelCopy = async () => {
  await FileManager.cancelOperationById({ id: 'my-copy-operation' });
};
```

### Read a large file as a Blob

```
import { FileManager } from '@capawesome-team/capacitor-file-manager';

const readLargeFile = async (uri: string) => {
  // Streams the file without base64 overhead.
  const { blob } = await FileManager.readFileAsBlob({ uri });
  return blob;
};
```

### Verify a file with a checksum

```
import { ChecksumAlgorithm, FileManager } from '@capawesome-team/capacitor-file-manager';

const verifyFile = async (uri: string, expectedChecksum: string) => {
  const { checksum } = await FileManager.getFileChecksum({
    uri,
    algorithm: ChecksumAlgorithm.Sha256,
  });
  return checksum === expectedChecksum;
};
```

### Check the storage space

```
import { FileManager } from '@capawesome-team/capacitor-file-manager';

const checkStorage = async () => {
  const { freeBytes } = await FileManager.getDeviceStorageInfo();
  const { cacheBytes } = await FileManager.getAppStorageInfo();
  if (cacheBytes > 100_000_000) {
    await FileManager.clearCache();
  }
  return freeBytes;
};
```

## API

- [`appendFile(...)`](#appendfile)
- [`cancelOperationById(...)`](#canceloperationbyid)
- [`clearCache()`](#clearcache)
- [`clearDirectory(...)`](#cleardirectory)
- [`copyDirectory(...)`](#copydirectory)
- [`copyFile(...)`](#copyfile)
- [`createDirectory(...)`](#createdirectory)
- [`deleteDirectory(...)`](#deletedirectory)
- [`deleteFile(...)`](#deletefile)
- [`exists(...)`](#exists)
- [`getAppStorageInfo()`](#getappstorageinfo)
- [`getDeviceStorageInfo()`](#getdevicestorageinfo)
- [`getDirectorySize(...)`](#getdirectorysize)
- [`getFileChecksum(...)`](#getfilechecksum)
- [`getMetadata(...)`](#getmetadata)
- [`getPersistedDirectories()`](#getpersisteddirectories)
- [`getUri(...)`](#geturi)
- [`moveDirectory(...)`](#movedirectory)
- [`moveFile(...)`](#movefile)
- [`persistDirectoryAccess(...)`](#persistdirectoryaccess)
- [`readDirectory(...)`](#readdirectory)
- [`readFile(...)`](#readfile)
- [`readFileAsBlob(...)`](#readfileasblob)
- [`releaseDirectoryAccess(...)`](#releasedirectoryaccess)
- [`truncateFile(...)`](#truncatefile)
- [`writeFile(...)`](#writefile)
- [`addListener('operationProgress', ...)`](#addlisteneroperationprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### appendFile(...)

```
appendFile(options: AppendFileOptions) => Promise<void>
```

Append data to a file.

If the file does not exist, it is created.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `AppendFileOptions` |

**Since:** 0.0.1

______________________________________________________________________

### cancelOperationById(...)

```
cancelOperationById(options: CancelOperationByIdOptions) => Promise<void>
```

Cancel a running directory operation.

The promise of the canceled operation is rejected with the `OPERATION_CANCELED` error code. Files that were already processed remain in place.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `CancelOperationByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### clearCache()

```
clearCache() => Promise<void>
```

Delete the contents of the app's cache directory.

**Since:** 0.0.1

______________________________________________________________________

### clearDirectory(...)

```
clearDirectory(options: ClearDirectoryOptions) => Promise<void>
```

Delete the contents of a directory but keep the directory itself.

Unlike deleting and recreating the directory, this preserves persisted access to the directory.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `ClearDirectoryOptions` |

**Since:** 0.0.1

______________________________________________________________________

### copyDirectory(...)

```
copyDirectory(options: CopyDirectoryOptions) => Promise<CopyDirectoryResult>
```

Copy a directory recursively.

Reports progress via the `operationProgress` event and can be canceled with `cancelOperationById(...)`.

On **Android**, the operation fails with the `WRITE_FAILED` error code if a document provider returns an entry name that cannot be used as a file name (e.g. a name containing `/`).

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `CopyDirectoryOptions` |

**Returns:** `Promise<CopyDirectoryResult>`

**Since:** 0.0.1

______________________________________________________________________

### copyFile(...)

```
copyFile(options: CopyFileOptions) => Promise<CopyFileResult>
```

Copy a file.

The file is copied natively with constant memory usage.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `CopyFileOptions` |

**Returns:** `Promise<CopyFileResult>`

**Since:** 0.0.1

______________________________________________________________________

### createDirectory(...)

```
createDirectory(options: CreateDirectoryOptions) => Promise<CreateDirectoryResult>
```

Create a new directory.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `CreateDirectoryOptions` |

**Returns:** `Promise<CreateDirectoryResult>`

**Since:** 0.0.1

______________________________________________________________________

### deleteDirectory(...)

```
deleteDirectory(options: DeleteDirectoryOptions) => Promise<void>
```

Delete a directory.

Reports progress via the `operationProgress` event and can be canceled with `cancelOperationById(...)`.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `DeleteDirectoryOptions` |

**Since:** 0.0.1

______________________________________________________________________

### deleteFile(...)

```
deleteFile(options: DeleteFileOptions) => Promise<void>
```

Delete a file.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DeleteFileOptions` |

**Since:** 0.0.1

______________________________________________________________________

### exists(...)

```
exists(options: ExistsOptions) => Promise<ExistsResult>
```

Check whether a file or directory exists.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `ExistsOptions` |

**Returns:** `Promise<ExistsResult>`

**Since:** 0.0.1

______________________________________________________________________

### getAppStorageInfo()

```
getAppStorageInfo() => Promise<GetAppStorageInfoResult>
```

Get the storage usage of the app itself.

**Returns:** `Promise<GetAppStorageInfoResult>`

**Since:** 0.0.1

______________________________________________________________________

### getDeviceStorageInfo()

```
getDeviceStorageInfo() => Promise<GetDeviceStorageInfoResult>
```

Get the total and free storage space of the device.

**Returns:** `Promise<GetDeviceStorageInfoResult>`

**Since:** 0.0.1

______________________________________________________________________

### getDirectorySize(...)

```
getDirectorySize(options: GetDirectorySizeOptions) => Promise<GetDirectorySizeResult>
```

Get the total size of a directory and all of its contents.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `GetDirectorySizeOptions` |

**Returns:** `Promise<GetDirectorySizeResult>`

**Since:** 0.0.1

______________________________________________________________________

### getFileChecksum(...)

```
getFileChecksum(options: GetFileChecksumOptions) => Promise<GetFileChecksumResult>
```

Calculate the checksum of a file.

The file is processed in a streaming manner with constant memory usage, so it works for files of any size.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `GetFileChecksumOptions` |

**Returns:** `Promise<GetFileChecksumResult>`

**Since:** 0.0.1

______________________________________________________________________

### getMetadata(...)

```
getMetadata(options: GetMetadataOptions) => Promise<GetMetadataResult>
```

Get the metadata of a file or directory.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetMetadataOptions` |

**Returns:** `Promise<GetMetadataResult>`

**Since:** 0.0.1

______________________________________________________________________

### getPersistedDirectories()

```
getPersistedDirectories() => Promise<GetPersistedDirectoriesResult>
```

Get all directories with persisted access.

Stale entries are refreshed and directories whose document no longer exists are released automatically. Call this method on app start and use the returned URIs instead of storing them yourself, since they may change between app launches.

Only available on Android and iOS.

**Returns:** `Promise<GetPersistedDirectoriesResult>`

**Since:** 0.0.1

______________________________________________________________________

### getUri(...)

```
getUri(options: GetUriOptions) => Promise<GetUriResult>
```

Construct the URI of a file or directory.

Provide either `directory` to resolve the path in a well-known sandbox directory or `parentUri` to resolve the path relative to any directory URI. The file or directory does not need to exist.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `GetUriOptions` |

**Returns:** `Promise<GetUriResult>`

**Since:** 0.0.1

______________________________________________________________________

### moveDirectory(...)

```
moveDirectory(options: MoveDirectoryOptions) => Promise<MoveDirectoryResult>
```

Move a directory.

Reports progress via the `operationProgress` event and can be canceled with `cancelOperationById(...)`.

On **Android**, the operation fails with the `WRITE_FAILED` error code if a document provider returns an entry name that cannot be used as a file name (e.g. a name containing `/`).

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `MoveDirectoryOptions` |

**Returns:** `Promise<MoveDirectoryResult>`

**Since:** 0.0.1

______________________________________________________________________

### moveFile(...)

```
moveFile(options: MoveFileOptions) => Promise<MoveFileResult>
```

Move a file.

A move within the same directory is performed as a rename.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `MoveFileOptions` |

**Returns:** `Promise<MoveFileResult>`

**Since:** 0.0.1

______________________________________________________________________

### persistDirectoryAccess(...)

```
persistDirectoryAccess(options: PersistDirectoryAccessOptions) => Promise<PersistDirectoryAccessResult>
```

Persist access to a directory across app launches.

Pass the values returned by `FilePicker.pickDirectory()` of the Capawesome File Picker plugin. Afterwards, the URIs of the persisted directory and its contents are accepted by every method of this plugin.

Requires version `8.1.0` or later of the Capawesome File Picker plugin.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `PersistDirectoryAccessOptions` |

**Returns:** `Promise<PersistDirectoryAccessResult>`

**Since:** 0.0.1

______________________________________________________________________

### readDirectory(...)

```
readDirectory(options: ReadDirectoryOptions) => Promise<ReadDirectoryResult>
```

Read the entries of a directory.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `ReadDirectoryOptions` |

**Returns:** `Promise<ReadDirectoryResult>`

**Since:** 0.0.1

______________________________________________________________________

### readFile(...)

```
readFile(options: ReadFileOptions) => Promise<ReadFileResult>
```

Read data from a file.

Use `offset` and `length` to read a byte range of a large file.

**Attention**: To read a whole large file, use `readFileAsBlob(...)` instead, since it streams the file and avoids out-of-memory (OOM) issues. The `readFile(...)` method reads the whole file into memory and encodes it as base64.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `ReadFileOptions` |

**Returns:** `Promise<ReadFileResult>`

**Since:** 0.0.1

______________________________________________________________________

### readFileAsBlob(...)

```
readFileAsBlob(options: ReadFileAsBlobOptions) => Promise<ReadFileAsBlobResult>
```

Read a file as a `Blob`.

This is the recommended way to read large files. The file is streamed without base64 encoding overhead.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `ReadFileAsBlobOptions` |

**Returns:** `Promise<ReadFileAsBlobResult>`

**Since:** 0.0.1

______________________________________________________________________

### releaseDirectoryAccess(...)

```
releaseDirectoryAccess(options: ReleaseDirectoryAccessOptions) => Promise<void>
```

Release persisted access to a directory.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `ReleaseDirectoryAccessOptions` |

**Since:** 0.0.1

______________________________________________________________________

### truncateFile(...)

```
truncateFile(options: TruncateFileOptions) => Promise<void>
```

Truncate a file to a given size.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `TruncateFileOptions` |

**Since:** 0.0.1

______________________________________________________________________

### writeFile(...)

```
writeFile(options: WriteFileOptions) => Promise<WriteFileResult>
```

Write data to a file.

If the file does not exist, it is created. If no `position` is provided, the existing content is overwritten.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `WriteFileOptions` |

**Returns:** `Promise<WriteFileResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('operationProgress', ...)

```
addListener(eventName: 'operationProgress', listenerFunc: (event: OperationProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a directory operation reports progress.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'operationProgress'`                     |
| **`listenerFunc`** | `(event: OperationProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### AppendFileOptions

| Prop           | Type       | Description                        | Default           | Since |
| -------------- | ---------- | ---------------------------------- | ----------------- | ----- |
| **`data`**     | `string`   | The data to append to the file.    |                   | 0.0.1 |
| **`encoding`** | `Encoding` | The encoding of the `data` option. | `Encoding.Base64` | 0.0.1 |
| **`uri`**      | `string`   | The URI of the file.               |                   | 0.0.1 |

#### CancelOperationByIdOptions

| Prop     | Type     | Description                                | Since |
| -------- | -------- | ------------------------------------------ | ----- |
| **`id`** | `string` | The identifier of the operation to cancel. | 0.0.1 |

#### ClearDirectoryOptions

| Prop      | Type     | Description               | Since |
| --------- | -------- | ------------------------- | ----- |
| **`uri`** | `string` | The URI of the directory. | 0.0.1 |

#### CopyDirectoryResult

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`uri`** | `string` | The URI of the created directory. | 0.0.1 |

#### CopyDirectoryOptions

| Prop        | Type     | Description                                                                                                                 | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**    | `string` | A unique identifier for this operation. It can be used to cancel the operation and to correlate `operationProgress` events. | 0.0.1 |
| **`toUri`** | `string` | The URI of the directory to copy to.                                                                                        | 0.0.1 |
| **`uri`**   | `string` | The URI of the directory to copy.                                                                                           | 0.0.1 |

#### CopyFileResult

| Prop      | Type     | Description                                                                                                                                            | Since |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`uri`** | `string` | The URI of the created file. This may differ from the requested URI, for example if the document provider had to rename the file to avoid a collision. | 0.0.1 |

#### CopyFileOptions

| Prop        | Type     | Description                     | Since |
| ----------- | -------- | ------------------------------- | ----- |
| **`toUri`** | `string` | The URI of the file to copy to. | 0.0.1 |
| **`uri`**   | `string` | The URI of the file to copy.    | 0.0.1 |

#### CreateDirectoryResult

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`uri`** | `string` | The URI of the created directory. | 0.0.1 |

#### CreateDirectoryOptions

| Prop            | Type      | Description                                          | Default | Since |
| --------------- | --------- | ---------------------------------------------------- | ------- | ----- |
| **`recursive`** | `boolean` | Whether or not to create missing parent directories. | `true`  | 0.0.1 |
| **`uri`**       | `string`  | The URI of the directory to create.                  |         | 0.0.1 |

#### DeleteDirectoryOptions

| Prop            | Type      | Description                                                                                                                                             | Default | Since |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`id`**        | `string`  | A unique identifier for this operation. It can be used to cancel the operation and to correlate `operationProgress` events.                             |         | 0.0.1 |
| **`recursive`** | `boolean` | Whether or not to delete the contents of the directory. If `false`, the call is rejected with the `NOT_EMPTY` error code if the directory is not empty. | `false` | 0.0.1 |
| **`uri`**       | `string`  | The URI of the directory to delete.                                                                                                                     |         | 0.0.1 |

#### DeleteFileOptions

| Prop      | Type     | Description                    | Since |
| --------- | -------- | ------------------------------ | ----- |
| **`uri`** | `string` | The URI of the file to delete. | 0.0.1 |

#### ExistsResult

| Prop         | Type      | Description                                  | Since |
| ------------ | --------- | -------------------------------------------- | ----- |
| **`exists`** | `boolean` | Whether or not the file or directory exists. | 0.0.1 |

#### ExistsOptions

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`uri`** | `string` | The URI of the file or directory. | 0.0.1 |

#### GetAppStorageInfoResult

| Prop             | Type     | Description                           | Since                                                                             |
| ---------------- | -------- | ------------------------------------- | --------------------------------------------------------------------------------- |
| **`cacheBytes`** | `number` | The size of the app's cache in bytes. | 0.0.1                                                                             |
| **`dataBytes`**  | \`number | null\`                                | The size of the app's data in bytes. Is `null` if the platform cannot provide it. |

#### GetDeviceStorageInfoResult

| Prop                   | Type     | Description                | Since                                                                                                                                                                          |
| ---------------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`allocatableBytes`** | \`number | null\`                     | The number of bytes the app is allowed to allocate, including space the system can free up for the app (e.g. by deleting caches). Is `null` if the platform cannot provide it. |
| **`freeBytes`**        | `number` | The number of free bytes.  | 0.0.1                                                                                                                                                                          |
| **`totalBytes`**       | `number` | The number of total bytes. | 0.0.1                                                                                                                                                                          |

#### GetDirectorySizeResult

| Prop       | Type     | Description                                                       | Since |
| ---------- | -------- | ----------------------------------------------------------------- | ----- |
| **`size`** | `number` | The total size of the directory and all of its contents in bytes. | 0.0.1 |

#### GetDirectorySizeOptions

| Prop      | Type     | Description               | Since |
| --------- | -------- | ------------------------- | ----- |
| **`uri`** | `string` | The URI of the directory. | 0.0.1 |

#### GetFileChecksumResult

| Prop           | Type     | Description                                                 | Since |
| -------------- | -------- | ----------------------------------------------------------- | ----- |
| **`checksum`** | `string` | The checksum of the file as a lowercase hexadecimal string. | 0.0.1 |

#### GetFileChecksumOptions

| Prop            | Type                | Description                                        | Since |
| --------------- | ------------------- | -------------------------------------------------- | ----- |
| **`algorithm`** | `ChecksumAlgorithm` | The algorithm to use for the checksum calculation. | 0.0.1 |
| **`uri`**       | `string`            | The URI of the file.                               | 0.0.1 |

#### GetMetadataResult

| Prop             | Type        | Description                                                   | Since                                                                                                                                       |
| ---------------- | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **`createdAt`**  | \`number    | null\`                                                        | The timestamp when the file or directory was created, in milliseconds since the epoch. Is `null` if the platform does not provide it.       |
| **`mimeType`**   | \`string    | null\`                                                        | The MIME type of the file. Is `null` for directories or if the type is unknown.                                                             |
| **`modifiedAt`** | \`number    | null\`                                                        | The timestamp when the file or directory was last modified, in milliseconds since the epoch. Is `null` if the platform does not provide it. |
| **`name`**       | `string`    | The name of the file or directory.                            | 0.0.1                                                                                                                                       |
| **`size`**       | `number`    | The size of the file in bytes. Is always `0` for directories. | 0.0.1                                                                                                                                       |
| **`type`**       | `EntryType` | The type of the entry.                                        | 0.0.1                                                                                                                                       |
| **`uri`**        | `string`    | The canonical URI of the file or directory.                   | 0.0.1                                                                                                                                       |

#### GetMetadataOptions

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`uri`** | `string` | The URI of the file or directory. | 0.0.1 |

#### GetPersistedDirectoriesResult

| Prop              | Type                   | Description                            | Since |
| ----------------- | ---------------------- | -------------------------------------- | ----- |
| **`directories`** | `PersistedDirectory[]` | The directories with persisted access. | 0.0.1 |

#### PersistedDirectory

| Prop       | Type     | Description                                                                                                                                                                                                          | Since |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`name`** | `string` | The name of the directory.                                                                                                                                                                                           | 0.0.1 |
| **`uri`**  | `string` | The URI of the directory. The URI identifies the persisted directory in all methods of this plugin. It may change between app launches, so do not store it yourself but retrieve it via `getPersistedDirectories()`. | 0.0.1 |

#### GetUriResult

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`uri`** | `string` | The URI of the file or directory. | 0.0.1 |

#### GetUriOptions

| Prop            | Type        | Description                                                                                                                                                                                                                                                                           | Since |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`directory`** | `Directory` | The well-known sandbox directory to resolve the path in. Either this option or `parentUri` must be provided.                                                                                                                                                                          | 0.0.1 |
| **`parentUri`** | `string`    | The URI of the directory to resolve the path in. Either this option or `directory` must be provided. On Android, constructing the URI of a non-existing entry inside a persisted directory is only supported for path-structured document providers such as the local device storage. | 0.0.1 |
| **`path`**      | `string`    | The path to resolve.                                                                                                                                                                                                                                                                  | 0.0.1 |

#### MoveDirectoryResult

| Prop      | Type     | Description                     | Since |
| --------- | -------- | ------------------------------- | ----- |
| **`uri`** | `string` | The URI of the moved directory. | 0.0.1 |

#### MoveDirectoryOptions

| Prop        | Type     | Description                                                                                                                 | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**    | `string` | A unique identifier for this operation. It can be used to cancel the operation and to correlate `operationProgress` events. | 0.0.1 |
| **`toUri`** | `string` | The URI of the directory to move to.                                                                                        | 0.0.1 |
| **`uri`**   | `string` | The URI of the directory to move.                                                                                           | 0.0.1 |

#### MoveFileResult

| Prop      | Type     | Description                                                                                                                                          | Since |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`uri`** | `string` | The URI of the moved file. This may differ from the requested URI, for example if the document provider had to rename the file to avoid a collision. | 0.0.1 |

#### MoveFileOptions

| Prop        | Type     | Description                     | Since |
| ----------- | -------- | ------------------------------- | ----- |
| **`toUri`** | `string` | The URI of the file to move to. | 0.0.1 |
| **`uri`**   | `string` | The URI of the file to move.    | 0.0.1 |

#### PersistDirectoryAccessResult

| Prop            | Type                 | Description              | Since |
| --------------- | -------------------- | ------------------------ | ----- |
| **`directory`** | `PersistedDirectory` | The persisted directory. | 0.0.1 |

#### PersistDirectoryAccessOptions

| Prop           | Type     | Description                                                                                                                                                                                                      | Since |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bookmark`** | `string` | The base64-encoded security-scoped bookmark of the directory as returned by `FilePicker.pickDirectory()`. Only returned by version `8.1.0` or later of the Capawesome File Picker plugin. Only available on iOS. | 0.0.1 |
| **`uri`**      | `string` | The URI of the directory as returned by `FilePicker.pickDirectory()` (named `path` in its result).                                                                                                               | 0.0.1 |

#### ReadDirectoryResult

| Prop          | Type               | Description                   | Since |
| ------------- | ------------------ | ----------------------------- | ----- |
| **`entries`** | `DirectoryEntry[]` | The entries of the directory. | 0.0.1 |

#### DirectoryEntry

| Prop             | Type        | Description                                                    | Since                                                                                                                           |
| ---------------- | ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **`createdAt`**  | \`number    | null\`                                                         | The timestamp when the entry was created, in milliseconds since the epoch. Is `null` if the platform does not provide it.       |
| **`mimeType`**   | \`string    | null\`                                                         | The MIME type of the entry. Is `null` for directories or if the type is unknown.                                                |
| **`modifiedAt`** | \`number    | null\`                                                         | The timestamp when the entry was last modified, in milliseconds since the epoch. Is `null` if the platform does not provide it. |
| **`name`**       | `string`    | The name of the entry.                                         | 0.0.1                                                                                                                           |
| **`size`**       | `number`    | The size of the entry in bytes. Is always `0` for directories. | 0.0.1                                                                                                                           |
| **`type`**       | `EntryType` | The type of the entry.                                         | 0.0.1                                                                                                                           |
| **`uri`**        | `string`    | The URI of the entry.                                          | 0.0.1                                                                                                                           |

#### ReadDirectoryOptions

| Prop         | Type     | Description                                                                    | Default | Since |
| ------------ | -------- | ------------------------------------------------------------------------------ | ------- | ----- |
| **`limit`**  | `number` | The maximum number of entries to return. By default, all entries are returned. |         | 0.0.1 |
| **`offset`** | `number` | The number of entries to skip.                                                 | `0`     | 0.0.1 |
| **`uri`**    | `string` | The URI of the directory to read.                                              |         | 0.0.1 |

#### ReadFileResult

| Prop       | Type     | Description                                                                  | Since |
| ---------- | -------- | ---------------------------------------------------------------------------- | ----- |
| **`data`** | `string` | The data read from the file, encoded as requested via the `encoding` option. | 0.0.1 |

#### ReadFileOptions

| Prop           | Type       | Description                                                                   | Default           | Since |
| -------------- | ---------- | ----------------------------------------------------------------------------- | ----------------- | ----- |
| **`encoding`** | `Encoding` | The encoding of the returned data.                                            | `Encoding.Base64` | 0.0.1 |
| **`length`**   | `number`   | The maximum number of bytes to read. By default, the file is read to the end. |                   | 0.0.1 |
| **`offset`**   | `number`   | The zero-based byte offset at which to start reading.                         | `0`               | 0.0.1 |
| **`uri`**      | `string`   | The URI of the file to read.                                                  |                   | 0.0.1 |

#### ReadFileAsBlobResult

| Prop       | Type   | Description                           | Since |
| ---------- | ------ | ------------------------------------- | ----- |
| **`blob`** | `Blob` | The contents of the file as a `Blob`. | 0.0.1 |

#### ReadFileAsBlobOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`uri`** | `string` | The URI of the file to read. | 0.0.1 |

#### ReleaseDirectoryAccessOptions

| Prop      | Type     | Description                         | Since |
| --------- | -------- | ----------------------------------- | ----- |
| **`uri`** | `string` | The URI of the persisted directory. | 0.0.1 |

#### TruncateFileOptions

| Prop       | Type     | Description                                | Default | Since |
| ---------- | -------- | ------------------------------------------ | ------- | ----- |
| **`size`** | `number` | The size in bytes to truncate the file to. | `0`     | 0.0.1 |
| **`uri`**  | `string` | The URI of the file to truncate.           |         | 0.0.1 |

#### WriteFileResult

| Prop      | Type     | Description                                                                                                                                            | Since |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`uri`** | `string` | The URI of the written file. This may differ from the requested URI, for example if the document provider had to rename the file to avoid a collision. | 0.0.1 |

#### WriteFileOptions

| Prop            | Type       | Description                                                                                                                                                 | Default           | Since |
| --------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- |
| **`data`**      | `string`   | The data to write to the file.                                                                                                                              |                   | 0.0.1 |
| **`encoding`**  | `Encoding` | The encoding of the `data` option.                                                                                                                          | `Encoding.Base64` | 0.0.1 |
| **`position`**  | `number`   | The zero-based byte offset at which to start writing. Existing content outside of the written range is preserved. If not provided, the file is overwritten. |                   | 0.0.1 |
| **`recursive`** | `boolean`  | Whether or not to create missing parent directories.                                                                                                        | `false`           | 0.0.1 |
| **`uri`**       | `string`   | The URI of the file to write.                                                                                                                               |                   | 0.0.1 |

#### PluginListenerHandle

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

#### OperationProgressEvent

| Prop                 | Type            | Description                                          | Since                                                                                                                 |
| -------------------- | --------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **`id`**             | \`string        | null\`                                               | The identifier of the operation as provided in the options of the operation. Is `null` if no identifier was provided. |
| **`operationType`**  | `OperationType` | The type of the operation.                           | 0.0.1                                                                                                                 |
| **`processedBytes`** | `number`        | The number of bytes that have been processed so far. | 0.0.1                                                                                                                 |
| **`processedFiles`** | `number`        | The number of files that have been processed so far. | 0.0.1                                                                                                                 |
| **`totalBytes`**     | \`number        | null\`                                               | The total number of bytes to process. Is `null` if the total is not yet known.                                        |
| **`totalFiles`**     | \`number        | null\`                                               | The total number of files to process. Is `null` if the total is not yet known.                                        |

### Enums

#### Encoding

| Members      | Value      | Description      | Since |
| ------------ | ---------- | ---------------- | ----- |
| **`Base64`** | `'BASE64'` | Base64 encoding. | 0.0.1 |
| **`Utf8`**   | `'UTF8'`   | UTF-8 encoding.  | 0.0.1 |

#### ChecksumAlgorithm

| Members      | Value      | Description | Since |
| ------------ | ---------- | ----------- | ----- |
| **`Md5`**    | `'MD5'`    | MD5.        | 0.0.1 |
| **`Sha1`**   | `'SHA1'`   | SHA-1.      | 0.0.1 |
| **`Sha256`** | `'SHA256'` | SHA-256.    | 0.0.1 |

#### EntryType

| Members         | Value         | Description  | Since |
| --------------- | ------------- | ------------ | ----- |
| **`Directory`** | `'DIRECTORY'` | A directory. | 0.0.1 |
| **`File`**      | `'FILE'`      | A file.      | 0.0.1 |

#### Directory

| Members              | Value                | Description                                                                                                                                                                                                                                                                                                                              | Since |
| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Cache`**          | `'CACHE'`            | The cache directory. The system may delete this directory to free up disk space. On Android, it maps to `getCacheDir()`. On iOS, it maps to `Library/Caches`. On Web, it maps to `opfs://cache`.                                                                                                                                         | 0.0.1 |
| **`Data`**           | `'DATA'`             | The directory holding application files. On Android, it maps to `getFilesDir()`. On iOS, it maps to `Documents`. On Web, it maps to `opfs://data`.                                                                                                                                                                                       | 0.0.1 |
| **`Documents`**      | `'DOCUMENTS'`        | The documents directory. On Android, it maps to the app-specific documents directory (`getExternalFilesDir(DIRECTORY_DOCUMENTS)`). Unlike `@capacitor/filesystem`, no storage permissions are required. Use persisted directories to access user-visible folders. On iOS, it maps to `Documents`. On Web, it maps to `opfs://documents`. | 0.0.1 |
| **`External`**       | `'EXTERNAL'`         | The external directory. On Android, it maps to `getExternalFilesDir(null)`. On iOS, it maps to `Documents`. On Web, it maps to `opfs://external`.                                                                                                                                                                                        | 0.0.1 |
| **`ExternalCache`**  | `'EXTERNAL_CACHE'`   | The external cache directory. On Android, it maps to `getExternalCacheDir()`. On iOS, it maps to `Library/Caches`. On Web, it maps to `opfs://external-cache`.                                                                                                                                                                           | 0.0.1 |
| **`Library`**        | `'LIBRARY'`          | The library directory. On Android, it maps to `getFilesDir()`. On iOS, it maps to `Library`. On Web, it maps to `opfs://library`.                                                                                                                                                                                                        | 0.0.1 |
| **`LibraryNoCloud`** | `'LIBRARY_NO_CLOUD'` | The library directory without cloud backup. On Android, it maps to `getFilesDir()`. On iOS, it maps to `Library/NoCloud`. On Web, it maps to `opfs://library-no-cloud`.                                                                                                                                                                  | 0.0.1 |
| **`Temporary`**      | `'TEMPORARY'`        | The temporary directory. On Android, it maps to `getCacheDir()`. On iOS, it maps to `tmp`. On Web, it maps to `opfs://temporary`.                                                                                                                                                                                                        | 0.0.1 |

#### OperationType

| Members      | Value      | Description         | Since |
| ------------ | ---------- | ------------------- | ----- |
| **`Copy`**   | `'COPY'`   | A copy operation.   | 0.0.1 |
| **`Delete`** | `'DELETE'` | A delete operation. | 0.0.1 |
| **`Move`**   | `'MOVE'`   | A move operation.   | 0.0.1 |

## Migration from `@capacitor/filesystem`

This plugin is a replacement for the sandbox operations of `@capacitor/filesystem`. Instead of passing `path` and `directory` to every method, construct the URI once with `getUri(...)` and pass it to any method:

```
// Before (@capacitor/filesystem)
const result = await Filesystem.readFile({ path: 'text.txt', directory: Directory.Data });

// After (@capawesome-team/capacitor-file-manager)
const { uri } = await FileManager.getUri({ path: 'text.txt', directory: Directory.Data });
const result = await FileManager.readFile({ uri });
```

The `Directory` enum members have the same names and values as in `@capacitor/filesystem`.

| `@capacitor/filesystem`             | `@capawesome-team/capacitor-file-manager`                                                    |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `appendFile(...)`                   | `getUri(...)` + `appendFile(...)`                                                            |
| `checkPermissions()`                | Not needed. Persisted directories replace the legacy storage permissions.                    |
| `copy(...)`                         | `getUri(...)` + `copyFile(...)` or `copyDirectory(...)`                                      |
| `deleteFile(...)`                   | `getUri(...)` + `deleteFile(...)`                                                            |
| `downloadFile(...)`                 | [File Transfer](https://capawesome.io/docs/sdks/capacitor/file-transfer/) plugin             |
| `getUri(...)`                       | `getUri(...)`                                                                                |
| `mkdir(...)`                        | `getUri(...)` + `createDirectory(...)`                                                       |
| `readdir(...)`                      | `getUri(...)` + `readDirectory(...)`                                                         |
| `readFile(...)`                     | `getUri(...)` + `readFile(...)`                                                              |
| `readFileInChunks(...)`             | `readFileAsBlob(...)`                                                                        |
| `rename(...)`                       | `getUri(...)` + `moveFile(...)` or `moveDirectory(...)`                                      |
| `requestPermissions()`              | Not needed. Persisted directories replace the legacy storage permissions.                    |
| `rmdir(...)`                        | `getUri(...)` + `deleteDirectory(...)`                                                       |
| `stat(...)`                         | `getUri(...)` + `getMetadata(...)`                                                           |
| `writeFile(...)`                    | `getUri(...)` + `writeFile(...)`                                                             |
| `Directory.ExternalStorage`         | Persisted directories. Direct access to the shared storage is blocked on Android 11+ anyway. |
| `Encoding.ASCII` / `Encoding.UTF16` | Dropped. Use `Encoding.Utf8` or `Encoding.Base64`.                                           |

## Working with other plugins

- **Sandbox URIs** (`file://`): Fully compatible with all file-related Capawesome plugins (File Opener, File Compressor, Zip, ...) — pass the URI wherever a `path` is expected.
- **Persisted directory URIs** (`content://` on Android, security-scoped `file://` on iOS): Not accepted by plugins that only support plain file paths. To bridge, copy the file into a sandbox directory (for example `Directory.Cache`) with `copyFile(...)`, operate on it there, and optionally copy it back.
- **Web URIs** (`opfs://`): Internal to this plugin. Use `readFileAsBlob(...)` to hand the data to other web APIs.

## FAQ

### How is this plugin different from other similar plugins?

It works with the user's own storage, not just your app's sandbox: pick a folder once and keep read and write access to it across app launches on Android and iOS, then run manager-grade operations there — recursive copy, move and delete with progress, checksums, and directory sizing. It also reports device and app storage usage, can clear the cache, and streams large files into your web code without base64 overhead. On the web, files live in the Origin Private File System with real directories and random access instead of base64 blobs in IndexedDB. If you only need to read and write files inside your app's own sandbox, a simpler approach is enough; if you need durable access to user-picked folders and integrity-checked file operations, this plugin is built for it. Backed by dedicated support.

### How do I read a whole large file?

Use `readFileAsBlob(...)`, which streams the file into a `Blob` without base64 overhead. Do not read a large file by calling `readFile(...)` with an increasing `offset` in a loop — on some storage providers every call has to skip to the offset again, which makes the loop drastically slower with every iteration. The `offset` and `length` options are intended for targeted reads, like a file header or a byte range.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user pick the files and directories that this plugin operates on.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open files in the matching app on the device.
- [File Transfer](https://capawesome.io/docs/sdks/capacitor/file-transfer/): Download and upload files, even while the app is in the background.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Compress and decompress files and directories.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-manager/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-manager/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-manager/LICENSE).

# Capacitor File Opener Plugin

Capacitor plugin to open a file with the default application.

## Features

The Capacitor File Opener plugin is one of the most complete file opening solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 📄 **Multiple file formats**: Open various file types with their default applications.
- 🌐 **Web support**: Open files using Blob objects on Web platform.
- 📱 **Native integration**: Uses system file associations on mobile platforms.
- 📁 **Flexible paths**: Support for file paths and content URIs on Android.
- 🔍 **MIME type detection**: Automatic MIME type detection or manual specification.
- 🤝 **Compatibility**: Works alongside the [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/), [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) and [Printer](https://capawesome.io/docs/sdks/capacitor/printer/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The File Opener plugin is typically used whenever an app hands a file over to another application, for example:

- **Document viewing**: Open downloaded documents such as PDFs, invoices, or reports with the device's default viewer app.
- **Post-download handling**: Let users open a file right after your app has downloaded or generated it.
- **Media playback**: Open images, videos, or audio files with the app the user has associated with that file type.
- **Web downloads**: Open files from `Blob` objects on the Web without saving them first.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [How to Take and Edit Photos in a Capacitor App](https://capawesome.io/blog/how-to-take-and-edit-photos-in-a-capacitor-app/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-opener` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-file-opener
npx cap sync
```

### Android

You need to specify the directories that contain the files you want to open. To do this, create a new file named `file_paths.xml` in the `res/xml` directory of your Android project (e.g. `android/app/src/main/res/xml/file_paths.xml`). Here is an example of the content of the file:

```
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="files" path="." />
    <cache-path name="cache" path="." />
    <external-files-path name="external-files" path="." />
    <external-cache-path name="external-cache" path="." />
    <external-path name="external" path="." />
</paths>
```

More information can be found in the [Android documentation](https://developer.android.com/training/secure-file-sharing/setup-sharing#DefineMetaData).

#### 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:

- `$androidxDocumentFileVersion` version of `androidx.documentfile:documentfile` (default: `1.1.0`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to open a file with the default application.

### Open a file with the default application

On Android and iOS, pass the path of the file. On Android, both file paths and content URIs are supported. The mime type is determined automatically, but you can also specify it with the `mimeType` option. On Web, pass a `Blob` instance instead:

```
import { FileOpener } from '@capawesome-team/capacitor-file-opener';

const open = async () => {
  await FileOpener.openFile({
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000073',
  });
};
```

## API

- [`openFile(...)`](#openfile)
- [Interfaces](#interfaces)

### openFile(...)

```
openFile(options: OpenFileOptions) => Promise<void>
```

Open a file with the default application.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `OpenFileOptions` |

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### OpenFileOptions

| Prop           | Type     | Description                                                                                                       | Since |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`blob`**     | `Blob`   | The blob instance of the file to open. Only available on Web.                                                     | 6.1.0 |
| **`path`**     | `string` | The path of the file. Only available on Android and iOS.                                                          | 0.0.1 |
| **`mimeType`** | `string` | The mime type of the file. If not specified, the mime type will be determined. Only available on Android and iOS. | 0.0.1 |

## FAQ

### Which file types can I open with this plugin?

The plugin can open various file types with their default applications. On Android and iOS, it uses the system file associations, so any file type for which the user has a suitable app installed can be opened. The mime type is determined automatically, but you can also specify it manually with the `mimeType` option.

### Why can't a file be opened on Android?

Make sure that the directory containing the file is declared in the `file_paths.xml` file of your Android project, as described in the [Installation](#installation) section. Without this configuration, the file can not be shared with the app that should open it.

### How do I open a file on the Web?

On the Web, pass a `Blob` instance to the `openFile(...)` method using the `blob` option. The `path` and `mimeType` options are only available on Android and iOS.

### Do I need to specify the mime type of the file?

No, if the `mimeType` option is not specified, the mime type will be determined automatically. You only need to set it if you want to override the detected type. This option is only available on Android and iOS.

### How is this plugin different from the File Picker plugin?

The [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugin lets the user select a file from the device and returns its path and metadata. The File Opener plugin does the opposite: it takes a file your app already has and opens it with the default application. Both plugins work well together, for example to pick a file and then open it.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress files with support for image formats like PNG, JPEG, and WebP.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file, directory, image, or video from the device.
- [Printer](https://capawesome.io/docs/sdks/capacitor/printer/): Print files, HTML, PDFs, and web views on Android and iOS.
- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive text, links, and files shared from other apps.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-opener/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-opener/LICENSE).

# Capacitor File Picker Plugin

Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system or gallery.

## Features

The Capacitor File Picker plugin is one of the most complete file selection solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 📂 **Directory picking**: Allows users to select a directory to retrieve all files.
- 🖼️ **Image picking**: Lets users select one or more images from the gallery.
- 🎥 **Video picking**: Lets users select one or more videos from the gallery.
- 📄 **File picking**: Lets users select one or more miscellaneous files from the file system.
- 📸 **HEIC to JPEG conversion**: Converts HEIC images to JPEG format on iOS.
- 📜 **File metadata**: Retrieves metadata such as file size, name, mime type, and last modified timestamp.
- 🤝 **Compatibility**: Works alongside the [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The File Picker plugin is typically used whenever an app needs the user to hand over a file, for example:

- **File uploads**: Let users attach documents such as PDFs or spreadsheets to a form and upload them to a server.
- **Profile and cover pictures**: Let users choose an existing photo from their gallery.
- **Media attachments**: Add images and videos to chat messages, posts, or support tickets.
- **Data imports**: Import CSV, JSON, or backup files into your app.

## Compatibility

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

## Guides

- [The File Handling Guide for Capacitor](https://capawesome.io/blog/capacitor-file-handling-guide/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-file-picker` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-file-picker
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$androidxActivityVersion` version of `androidx.activity:activity` (default: `1.13.0`)

#### Permissions

This API requires the following permissions be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Needed if you want to retrieve unredacted EXIF metadata from photos -->
<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
<!-- Needed if you want to read files from external storage -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
```

### iOS

#### Entitlements

To use this plugin with Mac Catalyst, your app must have the `com.apple.security.files.user-selected.read-only` entitlement enabled. This allows the app to read files selected by the user. Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.security.files.user-selected.read-only) for more information.

```
<key>com.apple.security.files.user-selected.read-only</key>
<true/>
```

If you don't want to use the plugin with Mac Catalyst, you can skip this step.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to pick files, images, videos, and directories, and how to process the selected files.

### Pick one or more files

Open the system file picker and let the user select one or more files of any type. The result contains the metadata (name, size, mime type, last modified timestamp) and, on Android and iOS, the path of each selected file:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickFiles = async () => {
  const result = await FilePicker.pickFiles();
  const file = result.files[0];
};
```

### Restrict the picker to specific file types

Use the `types` option to only accept certain [IANA media types](https://www.iana.org/assignments/media-types/media-types.xhtml), for example PDF documents:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickPdfFiles = async () => {
  const result = await FilePicker.pickFiles({
    types: ['application/pdf'],
  });
};
```

On Android, the system file picker can only offer files whose media type the device derives from the file extension. On Android 9 and older, `.json` files are not mapped to `application/json` and are reported as `application/octet-stream`. Third-party document providers may behave the same on any version. Add `application/octet-stream` to `types` if such files must be selectable.

### Pick images or videos from the gallery

Use `pickImages(...)`, `pickVideos(...)` or `pickMedia(...)` to open the photo gallery instead of the file picker. These methods are only available on Android and iOS:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickImages = async () => {
  const result = await FilePicker.pickImages();
};

const pickVideos = async () => {
  const result = await FilePicker.pickVideos();
};

const pickMedia = async () => {
  // Pick both images and videos
  const result = await FilePicker.pickMedia({ limit: 3 });
};
```

### Display a picked image in the web view

Use the `webPath` property to load a picked file in the web view, for example as the `src` of an `<img>` element:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const displayImage = async () => {
  const { files } = await FilePicker.pickImages({ limit: 1 });
  const image = document.createElement('img');
  image.src = files[0].webPath!;
  document.body.appendChild(image);
};
```

### Pick a directory

Let the user select a directory, for example to import all files it contains. Only available on Android and iOS:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickDirectory = async () => {
  const { path } = await FilePicker.pickDirectory();
};
```

### Upload a picked file to a server

On the Web, the picked file contains a `Blob` instance. On Android and iOS, load the file as a blob using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) and the file's `webPath`. You can then append the blob to a `FormData` object and upload it:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const uploadFile = async () => {
  const result = await FilePicker.pickFiles({ limit: 1 });
  const file = result.files[0];

  let blob: Blob;
  if (file.blob) {
    // Web
    blob = file.blob;
  } else {
    // Android and iOS
    const response = await fetch(file.webPath!);
    blob = await response.blob();
  }

  const formData = new FormData();
  formData.append('file', blob, file.name);
  await fetch('https://example.com/upload', {
    method: 'POST',
    body: formData,
  });
};
```

**Attention**: Avoid the `readData` option for large files. It loads the entire file into memory as a Base64 string, which can crash your app. The fetch-based approach above streams the file instead.

### Convert a HEIC image to JPEG

On iOS, photos are often stored in the HEIC format, which many servers and browsers cannot display. Use `convertHeicToJpeg(...)` to convert them. Only available on iOS:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertHeicToJpeg = async () => {
  const { path } = await FilePicker.convertHeicToJpeg({
    path: 'path/to/image.heic',
  });
};
```

### Convert a RAW image to JPEG

RAW images (e.g. DNG) are not transcoded when they are picked. Use `convertRawToJpeg(...)` to convert them. Only available on iOS:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertRawToJpeg = async () => {
  const { path } = await FilePicker.convertRawToJpeg({
    path: 'path/to/image.dng',
  });
};
```

### Check and request permissions

Picking files does not require any permissions since the operating system presents the picker. However, if you need the `ACCESS_MEDIA_LOCATION` or `READ_EXTERNAL_STORAGE` permission on Android (see [Installation](#installation)), you can check and request them:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const checkPermissions = async () => {
  const result = await FilePicker.checkPermissions();
};

const requestPermissions = async () => {
  const result = await FilePicker.requestPermissions();
};
```

### Listen for the picker being dismissed

On iOS, you can be notified when the user closes the picker without selecting anything:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const addPickerDismissedListener = async () => {
  await FilePicker.addListener('pickerDismissed', () => {
    console.log('Picker was dismissed');
  });
};
```

### Copy a file

Copy a picked file to a new location, for example into your app's data directory:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const copyFile = async () => {
  await FilePicker.copyFile({
    from: 'path/to/file',
    to: 'path/to/destination',
  });
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`convertHeicToJpeg(...)`](#convertheictojpeg)
- [`convertRawToJpeg(...)`](#convertrawtojpeg)
- [`copyFile(...)`](#copyfile)
- [`pickFiles(...)`](#pickfiles)
- [`pickDirectory()`](#pickdirectory)
- [`pickImages(...)`](#pickimages)
- [`pickMedia(...)`](#pickmedia)
- [`pickVideos(...)`](#pickvideos)
- [`requestPermissions(...)`](#requestpermissions)
- [`addListener('pickerDismissed', ...)`](#addlistenerpickerdismissed-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions to access files.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.1.0

______________________________________________________________________

### convertHeicToJpeg(...)

```
convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>
```

Convert a HEIC image to JPEG.

Only available on iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `ConvertHeicToJpegOptions` |

**Returns:** `Promise<ConvertHeicToJpegResult>`

**Since:** 0.6.0

______________________________________________________________________

### convertRawToJpeg(...)

```
convertRawToJpeg(options: ConvertRawToJpegOptions) => Promise<ConvertRawToJpegResult>
```

Convert a RAW image to JPEG.

Only available on iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `ConvertRawToJpegOptions` |

**Returns:** `Promise<ConvertRawToJpegResult>`

**Since:** 8.1.0

______________________________________________________________________

### copyFile(...)

```
copyFile(options: CopyFileOptions) => Promise<void>
```

Copy a file to a new location.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `CopyFileOptions` |

**Since:** 7.1.0

______________________________________________________________________

### pickFiles(...)

```
pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>
```

Open the file picker that allows the user to select one or more files.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PickFilesOptions` |

**Returns:** `Promise<PickFilesResult>`

______________________________________________________________________

### pickDirectory()

```
pickDirectory() => Promise<PickDirectoryResult>
```

Open a picker dialog that allows the user to select a directory.

Only available on Android and iOS.

**Returns:** `Promise<PickDirectoryResult>`

**Since:** 6.2.0

______________________________________________________________________

### pickImages(...)

```
pickImages(options?: PickMediaOptions | undefined) => Promise<PickImagesResult>
```

Pick one or more images from the gallery.

On iOS 13 and older it only allows to pick one image.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PickMediaOptions` |

**Returns:** `Promise<PickFilesResult>`

**Since:** 0.5.3

______________________________________________________________________

### pickMedia(...)

```
pickMedia(options?: PickMediaOptions | undefined) => Promise<PickMediaResult>
```

Pick one or more images or videos from the gallery.

On iOS 13 and older it only allows to pick one image or video.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PickMediaOptions` |

**Returns:** `Promise<PickFilesResult>`

**Since:** 0.5.3

______________________________________________________________________

### pickVideos(...)

```
pickVideos(options?: PickMediaOptions | undefined) => Promise<PickVideosResult>
```

Pick one or more videos from the gallery.

On iOS 13 and older it only allows to pick one video.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PickMediaOptions` |

**Returns:** `Promise<PickFilesResult>`

**Since:** 0.5.3

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions to access files.

Only available on Android.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.1.0

______________________________________________________________________

### addListener('pickerDismissed', ...)

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

Called when the file picker is dismissed.

Only available on iOS.

| Param              | Type                |
| ------------------ | ------------------- |
| **`eventName`**    | `'pickerDismissed'` |
| **`listenerFunc`** | `() => void`        |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.6.2

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.6.2

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop                      | Type              | Description                                                                                                             | Since |
| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----- |
| **`accessMediaLocation`** | `PermissionState` | Permission state for accessing media location. On Android, this requests/checks the `ACCESS_MEDIA_LOCATION` permission. | 6.1.0 |
| **`readExternalStorage`** | `PermissionState` | Permission state for reading external storage. On Android, this requests/checks the `READ_EXTERNAL_STORAGE` permission. | 6.1.0 |

#### ConvertHeicToJpegResult

| Prop       | Type     | Description                           | Since |
| ---------- | -------- | ------------------------------------- | ----- |
| **`path`** | `string` | The path of the converted JPEG image. | 0.6.0 |

#### ConvertHeicToJpegOptions

| Prop       | Type     | Description                 | Since |
| ---------- | -------- | --------------------------- | ----- |
| **`path`** | `string` | The path of the HEIC image. | 0.6.0 |

#### ConvertRawToJpegResult

| Prop       | Type     | Description                           | Since |
| ---------- | -------- | ------------------------------------- | ----- |
| **`path`** | `string` | The path of the converted JPEG image. | 8.1.0 |

#### ConvertRawToJpegOptions

| Prop       | Type     | Description                | Since |
| ---------- | -------- | -------------------------- | ----- |
| **`path`** | `string` | The path of the RAW image. | 8.1.0 |

#### CopyFileOptions

| Prop            | Type      | Description                                                     | Default | Since |
| --------------- | --------- | --------------------------------------------------------------- | ------- | ----- |
| **`from`**      | `string`  | The path of the file to copy.                                   |         | 7.1.0 |
| **`overwrite`** | `boolean` | Whether to overwrite if the file at destination already exists. | `true`  | 7.2.0 |
| **`to`**        | `string`  | The path to copy the file to.                                   |         | 7.1.0 |

#### PickFilesResult

| Prop        | Type           |
| ----------- | -------------- |
| **`files`** | `PickedFile[]` |

#### PickedFile

| Prop             | Type     | Description                                                                                                                                                                                                             | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`blob`**       | `Blob`   | The Blob instance of the file. Only available on Web.                                                                                                                                                                   |       |
| **`data`**       | `string` | The Base64 string representation of the data contained in the file. Is only provided if `readData` is set to `true`.                                                                                                    |       |
| **`duration`**   | `number` | The duration of the video in seconds. Only available on Android and iOS.                                                                                                                                                | 0.5.3 |
| **`height`**     | `number` | The height of the image or video in pixels. Only available on Android and iOS.                                                                                                                                          | 0.5.3 |
| **`mimeType`**   | `string` | The mime type of the file.                                                                                                                                                                                              |       |
| **`modifiedAt`** | `number` | The last modified timestamp of the file in milliseconds.                                                                                                                                                                | 0.5.9 |
| **`name`**       | `string` | The name of the file.                                                                                                                                                                                                   |       |
| **`path`**       | `string` | The path of the file. Only available on Android and iOS.                                                                                                                                                                |       |
| **`size`**       | `number` | The size of the file in bytes.                                                                                                                                                                                          |       |
| **`webPath`**    | `string` | The path of the file that can be used to load it in the web view, for example as the `src` of an `&lt;img&gt;` element. On the web, this is an object URL. Call `URL.revokeObjectURL(...)` when it is no longer needed. | 8.1.0 |
| **`width`**      | `number` | The width of the image or video in pixels. Only available on Android and iOS.                                                                                                                                           | 0.5.3 |

#### PickFilesOptions

| Prop           | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default | Since |
| -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`types`**    | `string[]` | List of accepted file types. Look at [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml) for a complete list of standard media types. Wildcards such as `image/*` are supported. On Android, the system file picker can only offer files whose media type the device derives from the file extension. On Android 9 and older, `.json` files are not mapped to `application/json` and are reported as `application/octet-stream`. Third-party document providers may behave the same on any version. Add `application/octet-stream` to `types` if such files must be selectable. |         |       |
| **`limit`**    | `number`   | The maximum number of files that the user can select. Setting this to `0` sets the selection limit to unlimited. Currently, only `0` and `1` are supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `0`     | 6.0.0 |
| **`readData`** | `boolean`  | Whether to read the file data. **Attention**: Reading large files can lead to app crashes. It's therefore not recommended to use this option. Instead, use the [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) to load the file as a blob, see [this example](https://capawesome.io/blog/capacitor-file-handling-guide/#read-a-file).                                                                                                                                                                                                                                      | `false` |       |

#### PickDirectoryResult

| Prop           | Type     | Description                                                                                                                                                         | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bookmark`** | `string` | The base64-encoded security-scoped bookmark of the selected directory. It can be used to retain access to the directory across app launches. Only available on iOS. | 8.1.0 |
| **`path`**     | `string` | The path to the selected directory.                                                                                                                                 | 6.2.0 |

#### PickMediaOptions

| Prop                  | Type      | Description                                                                                                                                                          | Default | Since |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`readData`**        | `boolean` | Whether to read the file data.                                                                                                                                       | `false` |       |
| **`skipTranscoding`** | `boolean` | Whether to avoid transcoding, if possible. On iOS, for example, HEIC images are automatically transcoded to JPEG. Only available on iOS.                             | `true`  |       |
| **`limit`**           | `number`  | The maximum number of files that the user can select. Setting this to `0` sets the selection limit to unlimited. On Android and Web, only `0` and `1` are supported. | `0`     | 5.2.0 |
| **`ordered`**         | `boolean` | Whether an ordered number is displayed instead of a check mark in the selection badge. Only available on iOS (15+).                                                  | `false` | 5.3.0 |

#### RequestPermissionsOptions

| Prop              | Type               | Description                 | Default                                          | Since |
| ----------------- | ------------------ | --------------------------- | ------------------------------------------------ | ----- |
| **`permissions`** | `PermissionType[]` | The permissions to request. | `["accessMediaLocation", "readExternalStorage"]` | 6.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### PickImagesOptions

`PickMediaOptions`

#### PickImagesResult

`PickMediaResult`

#### PickMediaResult

`PickFilesResult`

#### PickVideosOptions

`PickMediaOptions`

#### PickVideosResult

`PickMediaResult`

#### PermissionType

`'accessMediaLocation' | 'readExternalStorage'`

## FAQ

### How do I upload a picked file to a server?

On the Web, the picked file already contains a `Blob` instance that you can append to a `FormData` object. On Android and iOS, load the file as a blob using the Fetch API and the file's path, then upload it the same way. See the [usage example](#upload-a-picked-file-to-a-server) above and [The File Handling Guide for Capacitor](https://capawesome.io/blog/capacitor-file-handling-guide/) for a complete walkthrough.

### Why does my app crash when picking large files?

This usually happens when the `readData` option is enabled. It reads the entire file into memory as a Base64 string, which can exceed the available memory for large files. Keep `readData` disabled (the default) and load the file as a blob using the Fetch API instead, as shown in the [usage example](#upload-a-picked-file-to-a-server) above.

### What is the difference between `pickFiles`, `pickImages`, `pickMedia` and `pickVideos`?

The `pickFiles(...)` method opens the system file picker and supports any file type on Android, iOS and Web. The `pickImages(...)`, `pickVideos(...)` and `pickMedia(...)` methods open the photo gallery instead, which provides a more familiar experience for selecting photos and videos, and are only available on Android and iOS.

### Do I need any runtime permissions to pick files?

No, picking files itself does not require any runtime permissions because the operating system presents the picker on behalf of your app. On Android, the `ACCESS_MEDIA_LOCATION` permission is only needed to retrieve unredacted EXIF metadata from photos, and `READ_EXTERNAL_STORAGE` is only needed to read files from external storage. On iOS, no privacy descriptions are required.

### How is this plugin different from the Capacitor Camera and Filesystem plugins?

The Capacitor Camera plugin takes a photo with the camera or picks images from the gallery, but it does not support other file types. The Capacitor Filesystem plugin reads and writes files at known paths, but it does not provide any user interface for selecting them. The File Picker plugin fills this gap: it lets the user select any file, directory, image, or video and returns its path and metadata, which you can then process with other plugins.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress images before uploading them.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a picked file with the default application.
- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive files shared from other apps.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Zip and unzip files and directories.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/LICENSE).

## Credits

This plugin is based on the [Capacitor File Picker](https://github.com/capawesome-team/capacitor-file-picker) plugin. Thanks to everyone who contributed to the project!

# Capacitor File Transfer Plugin

Capacitor plugin for reliable background file uploads and downloads that survive the app being backgrounded. Task-based transfers with pause/resume, progress events, retries, and a persisted task store.

## Features

The Capacitor File Transfer plugin brings robust, task-based file transfers to your Capacitor app. Here are some of the key features:

- ⬆️ **Uploads**: Binary (raw body, e.g. S3 presigned URLs) and `multipart/form-data` uploads.
- ⬇️ **Downloads**: Streamed downloads directly to a file on the device.
- 🔋 **Background Continuation**: Transfers keep running while the app is in the background — a background `URLSession` on iOS and a `dataSync` foreground service driven by our own OkHttp engine on Android.
- ⏯️ **Pause & Resume**: Downloads can be paused and resumed, even after the process was killed (via resume data on iOS and HTTP `Range` requests on Android).
- 📊 **Progress Events**: Throttled progress events with transferred and total bytes.
- 💾 **Persisted Tasks**: Transfers are persisted and can be queried after an app restart.
- 🔁 **Retries**: Automatic retries with backoff on network errors.
- 🔒 **Honest Semantics**: No fake pause and no hidden private APIs — documented behavior across foreground, background, and force-quit.
- 🤝 **Compatibility**: Works hand in hand with the [File Manager](https://capawesome.io/docs/sdks/capacitor/file-manager/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The File Transfer plugin is typically used whenever an app needs to move large files between the device and a server, for example:

- **Offline-first content**: Download large assets such as videos, maps, or course material for offline use and let the transfer continue while the user leaves the app.
- **Media uploads**: Upload photos and videos captured in your app to your own backend or directly to an S3 presigned URL, without blocking the user interface.
- **Resumable downloads**: Let users pause and resume large downloads, even after the app process was killed, and retry automatically after network errors.
- **Transfer manager UI**: Build a download or upload manager with live progress bars, using the throttled progress events and the persisted task store.
- **Wi-Fi-only transfers**: Restrict large transfers to unmetered networks so that users don't consume their mobile data plan.
- **Document synchronization**: Keep documents in sync with your backend in the background, then open or compress them with the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugins.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor File Transfer Plugin](https://capawesome.io/blog/announcing-the-capacitor-file-transfer-plugin/): Task-based background transfers with pause and resume, retries, and a persisted task store.
- [An Alternative to cordova-plugin-file-transfer](https://capawesome.io/blog/alternative-to-cordova-plugin-file-transfer/): Compares the XHR advice, this plugin, and its background transfer API.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-transfer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-file-transfer
npx cap sync
```

### Android

The plugin declares the `INTERNET`, `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_DATA_SYNC` and `POST_NOTIFICATIONS` permissions and the `dataSync` foreground service in its own manifest, so no manifest changes are required.

On Android 13 (API level 33) and higher, the progress notification is only shown if the user has granted the `POST_NOTIFICATIONS` runtime permission. Transfers still run without it — only the notification is hidden. Call `requestPermissions()` before starting a transfer if you want the notification to appear:

```
const { notifications } = await FileTransfer.requestPermissions();
if (notifications !== 'granted') {
  // The transfer will run, but no progress notification is shown.
}
```

The foreground service notification itself is shown while a transfer runs — Android requires a foreground service to have one. On Android 12+, a transfer that starts while the app is in the background (e.g. after waiting for an unmetered network) runs without the foreground service, since Android does not allow starting one from the background. The per-transfer progress notification is opt-in and off by default:

```
await FileTransfer.startDownload({
  url,
  path,
  androidNotification: { title: 'Downloading', progress: true },
});
```

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
-keep class okhttp3.** { *; }
-keep class okio.** { *; }
```

#### 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:

- `$okhttpVersion` version of `com.squareup.okhttp3:okhttp` (default: `4.12.0`)

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

### iOS

The plugin uses a background `URLSession` so that transfers continue while your app is suspended. When a transfer finishes while the app is not running, iOS relaunches the app in the background and needs the transfer's completion handler to be forwarded to the plugin.

Add the following method to your app's `AppDelegate.swift` to forward the handler:

```
import Foundation

extension AppDelegate {
    func application(
        _ application: UIApplication,
        handleEventsForBackgroundURLSession identifier: String,
        completionHandler: @escaping () -> Void
    ) {
        NotificationCenter.default.post(
            name: Notification.Name("io.capawesome.capacitorjs.plugins.filetransfer.handleEventsForBackgroundURLSession"),
            object: completionHandler
        )
    }
}
```

Without this hook, background transfers still complete, but iOS may not be able to wake your app to deliver the final events promptly.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to download and upload files, listen for transfer events, pause, resume, and cancel transfers, and retrieve known transfers.

### Download a file

Start a background download with `startDownload(...)`. The method resolves immediately with the identifier of the transfer, while the download itself continues in the background:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const startDownload = async () => {
  const { id } = await FileTransfer.startDownload({
    url: 'https://example.com/file.zip',
    path: '/path/to/destination/file.zip',
    headers: {
      Authorization: 'Bearer <token>',
    },
    network: 'unmetered',
    maxRetries: 3,
    androidNotification: {
      title: 'Downloading file',
      text: 'The file is being downloaded.',
    },
  });
  return id;
};
```

### Upload a file

Upload a file from the device with `startUpload(...)`. By default, the file is sent as a `multipart/form-data` request, where `fileField` defines the name of the form field that contains the file and `formFields` adds further fields to the request:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const startUpload = async () => {
  const { id } = await FileTransfer.startUpload({
    url: 'https://example.com/upload',
    path: '/path/to/source/file.jpg',
    uploadType: 'multipart',
    fileField: 'file',
    mimeType: 'image/jpeg',
    formFields: {
      albumId: '42',
    },
  });
  return id;
};
```

### Upload to an S3 presigned URL

Presigned URLs expect the raw file as the request body. Use `uploadType: 'binary'` and the `PUT` method:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const uploadToPresignedUrl = async () => {
  const { id } = await FileTransfer.startUpload({
    url: 'https://example.com/presigned-url',
    path: '/path/to/source/file.jpg',
    method: 'PUT',
    uploadType: 'binary',
    mimeType: 'image/jpeg',
  });
  return id;
};
```

### Listen for transfer events

Transfers report their state through events: `transferProgress` is emitted repeatedly while a transfer is running, `transferCompleted` when it succeeds, and `transferFailed` when it fails. Completed and failed events that occur while no listener is registered are retained and delivered as soon as a listener is added:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const addTransferListeners = async () => {
  await FileTransfer.addListener('transferProgress', event => {
    console.log(`Transfer ${event.id}: ${event.bytes}/${event.totalBytes}`);
  });
  await FileTransfer.addListener('transferCompleted', event => {
    console.log(`Transfer ${event.id} completed: `, event.path);
  });
  await FileTransfer.addListener('transferFailed', event => {
    console.error(`Transfer ${event.id} failed: `, event.errorCode, event.message);
  });
};
```

### Pause and resume a transfer

Pause a running download with `pauseTransferById(...)` and continue it later with `resumeTransferById(...)`, using the identifier returned by `startDownload(...)`. Paused downloads survive process death and can therefore also be resumed after an app restart. Uploads cannot be paused in this version:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const pauseTransferById = async (id: string) => {
  await FileTransfer.pauseTransferById({ id });
};

const resumeTransferById = async (id: string) => {
  await FileTransfer.resumeTransferById({ id });
};
```

### Cancel a transfer

Cancel a running or paused transfer with `cancelTransferById(...)`. Any partially transferred data is deleted, so the transfer cannot be resumed afterwards:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const cancelTransferById = async (id: string) => {
  await FileTransfer.cancelTransferById({ id });
};
```

### Retrieve transfers

Get a single transfer with `getTransferById(...)` or all known transfers with `getTransfers()`. Transfers are persisted, so both methods also return transfers that were restored after an app restart, for example to rebuild a transfer list on app start:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const getTransferById = async (id: string) => {
  const { transfer } = await FileTransfer.getTransferById({ id });
  return transfer;
};

const getRunningTransfers = async () => {
  const { transfers } = await FileTransfer.getTransfers();
  return transfers.filter(transfer => transfer.state === 'running');
};
```

### Remove all listeners

Remove all listeners that your app has registered, for example when a view is destroyed:

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

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

## API

- [`cancelTransferById(...)`](#canceltransferbyid)
- [`checkPermissions()`](#checkpermissions)
- [`getTransferById(...)`](#gettransferbyid)
- [`getTransfers()`](#gettransfers)
- [`pauseTransferById(...)`](#pausetransferbyid)
- [`requestPermissions()`](#requestpermissions)
- [`resumeTransferById(...)`](#resumetransferbyid)
- [`startDownload(...)`](#startdownload)
- [`startUpload(...)`](#startupload)
- [`addListener('transferCompleted', ...)`](#addlistenertransfercompleted-)
- [`addListener('transferFailed', ...)`](#addlistenertransferfailed-)
- [`addListener('transferProgress', ...)`](#addlistenertransferprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### cancelTransferById(...)

```
cancelTransferById(options: CancelTransferByIdOptions) => Promise<void>
```

Cancel a running or paused transfer and delete any partially transferred data.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `CancelTransferByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the current permission status.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### getTransferById(...)

```
getTransferById(options: GetTransferByIdOptions) => Promise<GetTransferByIdResult>
```

Get a single transfer by its identifier.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `GetTransferByIdOptions` |

**Returns:** `Promise<GetTransferByIdResult>`

**Since:** 0.0.1

______________________________________________________________________

### getTransfers()

```
getTransfers() => Promise<GetTransfersResult>
```

Get all known transfers, including transfers that were restored after an app restart.

**Returns:** `Promise<GetTransfersResult>`

**Since:** 0.0.1

______________________________________________________________________

### pauseTransferById(...)

```
pauseTransferById(options: PauseTransferByIdOptions) => Promise<void>
```

Pause a running transfer.

Downloads are paused so that they survive process death and can be resumed later. Uploads and downloads that are not resumable cannot be paused and are rejected with the `TRANSFER_NOT_PAUSABLE` error code.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `PauseTransferByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to post the progress notification.

On **Android 12 and older**, on **iOS** and on the **web**, this resolves without prompting since no notification permission is required.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### resumeTransferById(...)

```
resumeTransferById(options: ResumeTransferByIdOptions) => Promise<void>
```

Resume a paused or failed transfer.

Only transfers in the `paused` or `failed` state are resumed. For a transfer in any other state, this resolves without effect.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `ResumeTransferByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### startDownload(...)

```
startDownload(options: StartDownloadOptions) => Promise<StartDownloadResult>
```

Start a background download and immediately return its identifier.

The download continues while the app is in the background.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartDownloadOptions` |

**Returns:** `Promise<StartDownloadResult>`

**Since:** 0.0.1

______________________________________________________________________

### startUpload(...)

```
startUpload(options: StartUploadOptions) => Promise<StartUploadResult>
```

Start a background upload and immediately return its identifier.

The upload continues while the app is in the background.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `StartUploadOptions` |

**Returns:** `Promise<StartUploadResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('transferCompleted', ...)

```
addListener(eventName: 'transferCompleted', listenerFunc: (event: TransferCompletedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a transfer completes successfully.

Completed events that occur while no listener is registered are retained and delivered once a listener is added.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'transferCompleted'`                     |
| **`listenerFunc`** | `(event: TransferCompletedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('transferFailed', ...)

```
addListener(eventName: 'transferFailed', listenerFunc: (event: TransferFailedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a transfer fails.

Failed events that occur while no listener is registered are retained and delivered once a listener is added.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'transferFailed'`                     |
| **`listenerFunc`** | `(event: TransferFailedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('transferProgress', ...)

```
addListener(eventName: 'transferProgress', listenerFunc: (event: TransferProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called repeatedly while a transfer is running to report its progress.

The event is throttled to roughly one emission every 100 milliseconds per transfer.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'transferProgress'`                     |
| **`listenerFunc`** | `(event: TransferProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### CancelTransferByIdOptions

| Prop     | Type     | Description                               | Since |
| -------- | -------- | ----------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the transfer to cancel. | 0.0.1 |

#### PermissionStatus

| Prop                | Type              | Description                                                                                                                                                                                                                                                                  | Since |
| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`notifications`** | `PermissionState` | Permission state for posting notifications. The progress notification is only shown if this is `granted`. Transfers still run without it. On **Android 12 and older**, on **iOS** and on the **web**, this is always `granted` since no notification permission is required. | 0.0.1 |

#### GetTransferByIdResult

| Prop           | Type       | Description                             | Since |
| -------------- | ---------- | --------------------------------------- | ----- |
| **`transfer`** | `Transfer` | The transfer with the given identifier. | 0.0.1 |

#### Transfer

| Prop             | Type            | Description                                            | Since                                                        |
| ---------------- | --------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| **`id`**         | `string`        | The identifier of the transfer.                        | 0.0.1                                                        |
| **`type`**       | `TransferType`  | The direction of the transfer.                         | 0.0.1                                                        |
| **`state`**      | `TransferState` | The current state of the transfer.                     | 0.0.1                                                        |
| **`url`**        | `string`        | The URL of the transfer.                               | 0.0.1                                                        |
| **`path`**       | `string`        | The path on the device of the transfer.                | 0.0.1                                                        |
| **`bytes`**      | `number`        | The number of bytes that have been transferred so far. | 0.0.1                                                        |
| **`totalBytes`** | \`number        | null\`                                                 | The total number of bytes to transfer, or `null` if unknown. |

#### GetTransferByIdOptions

| Prop     | Type     | Description                            | Since |
| -------- | -------- | -------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the transfer to get. | 0.0.1 |

#### GetTransfersResult

| Prop            | Type         | Description                      | Since |
| --------------- | ------------ | -------------------------------- | ----- |
| **`transfers`** | `Transfer[]` | The list of all known transfers. | 0.0.1 |

#### PauseTransferByIdOptions

| Prop     | Type     | Description                              | Since |
| -------- | -------- | ---------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the transfer to pause. | 0.0.1 |

#### ResumeTransferByIdOptions

| Prop     | Type     | Description                               | Since |
| -------- | -------- | ----------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the transfer to resume. | 0.0.1 |

#### StartDownloadResult

| Prop     | Type     | Description                             | Since |
| -------- | -------- | --------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the started transfer. | 0.0.1 |

#### StartDownloadOptions

| Prop                      | Type                          | Description                                                                                                                                                                                                                                                    | Default                                 | Since   |
| ------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- |
| **`androidNotification`** | `TransferNotificationOptions` | The configuration of the foreground service notification. Only available on Android.                                                                                                                                                                           |                                         | 0.0.1   |
| **`url`**                 | `string`                      | The URL to download the file from.                                                                                                                                                                                                                             |                                         | 0.0.1   |
| **`path`**                | `string`                      | The path on the device where the downloaded file should be stored.                                                                                                                                                                                             |                                         | 0.0.1   |
| **`headers`**             | `Record<string, string>`      | The HTTP headers to send with the request.                                                                                                                                                                                                                     |                                         | 0.0.1   |
| **`method`**              | \`'GET'                       | 'POST'\`                                                                                                                                                                                                                                                       | The HTTP method to use for the request. | `'GET'` |
| **`network`**             | `TransferNetwork`             | The network type that is required for the transfer to run. Use `'unmetered'` to only run the transfer on unmetered networks (e.g. Wi-Fi). The transfer waits until such a network is available. On **Android**, it stays in the `pending` state while waiting. | `'any'`                                 | 0.0.1   |
| **`resumable`**           | `boolean`                     | Whether the download may be resumed after a pause or an interruption. Requires the server to support the HTTP `Range` header.                                                                                                                                  | `true`                                  | 0.0.1   |
| **`maxRetries`**          | `number`                      | The maximum number of times the transfer is retried after a network error.                                                                                                                                                                                     | `0`                                     | 0.0.1   |

#### TransferNotificationOptions

The configuration of the Android foreground service notification.

On **Android 12+**, a transfer that starts while the app is in the background (e.g. after waiting for an unmetered network) runs without the foreground service and its notification, since Android does not allow starting one from the background.

Only available on Android.

| Prop              | Type      | Description                                                                                                                                                                                                                                   | Default           | Since |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- |
| **`title`**       | `string`  | The title of the notification.                                                                                                                                                                                                                |                   | 0.0.1 |
| **`progress`**    | `boolean` | Whether to show a separate notification with a progress bar for this transfer. The foreground service notification is shown while a transfer runs, because Android requires it. This option only adds the per-transfer progress notification. | `false`           | 0.0.1 |
| **`text`**        | `string`  | The text of the notification.                                                                                                                                                                                                                 |                   | 0.0.1 |
| **`channelName`** | `string`  | The name of the notification channel.                                                                                                                                                                                                         | `'File Transfer'` | 0.0.1 |

#### StartUploadResult

| Prop     | Type     | Description                             | Since |
| -------- | -------- | --------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the started transfer. | 0.0.1 |

#### StartUploadOptions

| Prop                      | Type                          | Description                                                                                                                                                                                                                                                    | Default                                 | Since    |
| ------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- |
| **`androidNotification`** | `TransferNotificationOptions` | The configuration of the foreground service notification. Only available on Android.                                                                                                                                                                           |                                         | 0.0.1    |
| **`url`**                 | `string`                      | The URL to upload the file to.                                                                                                                                                                                                                                 |                                         | 0.0.1    |
| **`path`**                | `string`                      | The path on the device of the file to upload.                                                                                                                                                                                                                  |                                         | 0.0.1    |
| **`method`**              | \`'POST'                      | 'PUT'\`                                                                                                                                                                                                                                                        | The HTTP method to use for the request. | `'POST'` |
| **`uploadType`**          | `TransferUploadType`          | The type of upload to perform. Use `'binary'` to send the raw file as the request body (e.g. for S3 presigned URLs) or `'multipart'` to send a `multipart/form-data` request.                                                                                  | `'multipart'`                           | 0.0.1    |
| **`fileField`**           | `string`                      | The name of the form field that contains the file. Only used when `uploadType` is `'multipart'`.                                                                                                                                                               | `'file'`                                | 0.0.1    |
| **`mimeType`**            | `string`                      | The MIME type of the file to upload.                                                                                                                                                                                                                           |                                         | 0.0.1    |
| **`formFields`**          | `Record<string, string>`      | The additional form fields to send with the request. Only used when `uploadType` is `'multipart'`.                                                                                                                                                             |                                         | 0.0.1    |
| **`headers`**             | `Record<string, string>`      | The HTTP headers to send with the request.                                                                                                                                                                                                                     |                                         | 0.0.1    |
| **`network`**             | `TransferNetwork`             | The network type that is required for the transfer to run. Use `'unmetered'` to only run the transfer on unmetered networks (e.g. Wi-Fi). The transfer waits until such a network is available. On **Android**, it stays in the `pending` state while waiting. | `'any'`                                 | 0.0.1    |
| **`maxRetries`**          | `number`                      | The maximum number of times the transfer is retried after a network error.                                                                                                                                                                                     | `0`                                     | 0.0.1    |

#### PluginListenerHandle

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

#### TransferCompletedEvent

| Prop               | Type     | Description                     | Since                                                                             |
| ------------------ | -------- | ------------------------------- | --------------------------------------------------------------------------------- |
| **`id`**           | `string` | The identifier of the transfer. | 0.0.1                                                                             |
| **`path`**         | \`string | null\`                          | The path on the device of the transferred file, or `null` for uploads.            |
| **`responseCode`** | \`number | null\`                          | The HTTP status code of the response, or `null` if not available.                 |
| **`responseBody`** | \`string | null\`                          | The body of the response, or `null` if not available. Only available for uploads. |

#### TransferFailedEvent

| Prop               | Type     | Description                       | Since                                                             |
| ------------------ | -------- | --------------------------------- | ----------------------------------------------------------------- |
| **`id`**           | `string` | The identifier of the transfer.   | 0.0.1                                                             |
| **`errorCode`**    | `string` | The error code of the failure.    | 0.0.1                                                             |
| **`message`**      | `string` | The error message of the failure. | 0.0.1                                                             |
| **`responseCode`** | \`number | null\`                            | The HTTP status code of the response, or `null` if not available. |

#### TransferProgressEvent

| Prop             | Type     | Description                                            | Since                                                                              |
| ---------------- | -------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| **`id`**         | `string` | The identifier of the transfer.                        | 0.0.1                                                                              |
| **`bytes`**      | `number` | The number of bytes that have been transferred so far. | 0.0.1                                                                              |
| **`totalBytes`** | \`number | null\`                                                 | The total number of bytes to transfer, or `null` if unknown.                       |
| **`progress`**   | \`number | null\`                                                 | The progress of the transfer as a value between `0` and `1`, or `null` if unknown. |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### TransferType

The direction of a transfer.

`'download' | 'upload'`

#### TransferState

The current state of a transfer.

`'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'canceled'`

#### TransferNetwork

The network type that is required for a transfer to run.

`'any' | 'unmetered'`

#### TransferUploadType

The type of upload to perform.

`'binary' | 'multipart'`

## Migration from `@capacitor/file-transfer`

| `@capacitor/file-transfer`     | `@capawesome-team/capacitor-file-transfer`                                                         |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| `downloadFile({ url, path })`  | `startDownload({ url, path })` → returns `{ id }` and continues in the background                  |
| `uploadFile({ url, path })`    | `startUpload({ url, path })` → returns `{ id }` and continues in the background                    |
| `addListener('progress', ...)` | `addListener('transferProgress', ...)`                                                             |
| *No equivalent*                | `pauseTransferById`, `resumeTransferById`, `cancelTransferById`, `getTransferById`, `getTransfers` |
| *No equivalent*                | `transferCompleted` and `transferFailed` events                                                    |

Transfers are asynchronous: `startDownload(...)` and `startUpload(...)` resolve immediately with a transfer `id`, and you observe completion through the `transferCompleted` and `transferFailed` events.

## FAQ

### Do transfers continue when the app is in the background?

Yes. On Android, transfers keep running in a `dataSync` foreground service, and on iOS, in a background `URLSession`. The following table summarizes what happens to a transfer in each app state:

| App State                     | Android                                                 | iOS                                                                                                                                                   |
| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Foreground                    | Runs.                                                   | Runs.                                                                                                                                                 |
| Backgrounded                  | Runs (via the `dataSync` foreground service).           | Runs (via the background `URLSession`).                                                                                                               |
| Killed by the OS (low memory) | Interrupted; restored as `failed`, downloads resumable. | Continued by the OS and delivered on relaunch.                                                                                                        |
| Force-quit by the user        | Interrupted; restored as `failed`, downloads resumable. | Canceled by the OS (documented OS behavior); on relaunch retried when `maxRetries > 0`, otherwise restored as `failed` with a `transferFailed` event. |

Resuming an interrupted download requires the server to support the HTTP `Range` header.

### Can I pause an upload?

Not in this version. Plain HTTP uploads have no standard resume mechanism, so `pauseTransferById(...)` rejects for uploads instead of faking it with a suspend. Downloads, on the other hand, can be paused and resumed at any time, even after the app process was killed.

### Is this available on the web?

No. Transfers require a native background API, so `startDownload(...)` and `startUpload(...)` reject as unavailable on the web, as do `pauseTransferById(...)` and `resumeTransferById(...)`. The remaining methods are implemented and simply report that no transfer exists.

### How is this plugin different from the `@capacitor/file-transfer` plugin?

This plugin offers advanced features such as background continuation on Android and iOS, pause and resume that survives process death, a task-based API with a persisted task store, throttled progress events, automatic retries, and network constraints, and comes with priority support from the Capawesome Team. See the [Migration from `@capacitor/file-transfer`](#migration-from-capacitorfile-transfer) section for a side-by-side overview of both APIs.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress files before uploading them.
- [File Manager](https://capawesome.io/docs/sdks/capacitor/file-manager/): Access and manage the user's storage natively.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open the transferred files in another app.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-transfer/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-transfer/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-transfer/LICENSE).

# Capacitor Flic Plugin

Unofficial Capacitor plugin for [Flic](https://flic.io/) smart buttons.[1](#fn:1)

## Features

- 🔍 **Pairing wizard**: Pair new Flic buttons with a single call using the integrated scan wizard.
- 🔗 **Connection management**: Connect, disconnect and forget buttons at any time.
- 🖱️ **Button events**: Listen for single click, double click, hold, down and up events.
- 📥 **Queued events**: Receive events that occurred while the button was disconnected.
- 🔋 **Battery level**: Read the last known battery voltage of each button.
- 🔐 **Permissions**: Check and request the required permissions with a single call.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Flic plugin is typically used to trigger app actions with a physical button, for example:

- **Smart home control**: Toggle lights, scenes or other devices with a single press.
- **Safety buttons**: Send an alert or start a call when the user presses the button.
- **Time tracking**: Start and stop timers without opening the app.
- **Accessibility**: Provide a simple physical trigger for essential app actions.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-flic` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-flic
npx cap sync
```

### Android

The plugin already declares all required Bluetooth permissions in its manifest, so no additional configuration is required.

The [flic2lib-android](https://github.com/50ButtonsEach/flic2lib-android) library is resolved from [JitPack](https://jitpack.io/). The plugin already declares the JitPack repository in its `build.gradle` file. If your project restricts repository declarations to the settings file (e.g. via `dependencyResolutionManagement` with `FAIL_ON_PROJECT_REPOS`), add the JitPack repository to your `settings.gradle` file:

```
dependencyResolutionManagement {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}
```

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$flic2libVersion` version of `com.github.50ButtonsEach:flic2lib-android` (default: `2.0.1`)

### iOS

Add the `NSBluetoothAlwaysUsageDescription` and `NSBluetoothPeripheralUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why the app needs access to Bluetooth:

```
<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app needs access to Bluetooth to communicate with your Flic buttons.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>The app needs access to Bluetooth to communicate with your Flic buttons.</string>
```

If you want to receive button events while the app is in the background, you must also enable the `Uses Bluetooth LE accessories` background mode in the **Signing & Capabilities** section of your Xcode project and call `initialize(...)` with the `iosBackground` option set to `true`.

## Configuration

No configuration required for this plugin.

## Usage

### Initialize the plugin

Call `initialize()` as soon as possible after the app has launched to minimize the delay of any pending button events:

```
import { Flic } from '@capawesome/capacitor-flic';

const initialize = async () => {
  await Flic.initialize({ iosBackground: true });
};
```

### Pair a new button

To pair a new button, start a scan and press and hold the button for at least 6 seconds:

```
import { Flic, ScanStatus } from '@capawesome/capacitor-flic';

const pairButton = async () => {
  await Flic.addListener('scanStatusChanged', (event) => {
    if (event.status === ScanStatus.Discovered) {
      console.log('Button discovered. Keep holding it...');
    }
  });
  const { button } = await Flic.startScan();
  return button;
};
```

### List paired buttons

```
import { Flic } from '@capawesome/capacitor-flic';

const getButtons = async () => {
  const { buttons } = await Flic.getButtons();
  return buttons;
};
```

### Connect a button

After an app restart, each paired button must be connected again:

```
import { Flic } from '@capawesome/capacitor-flic';

const connectButtons = async () => {
  const { buttons } = await Flic.getButtons();
  for (const button of buttons) {
    await Flic.connectButtonById({ id: button.id });
  }
};
```

### Listen for button events

```
import { Flic } from '@capawesome/capacitor-flic';

const addListeners = async () => {
  await Flic.addListener('buttonSingleClick', (event) => {
    console.log('Button was clicked', event);
  });
  await Flic.addListener('buttonDoubleClick', (event) => {
    console.log('Button was double clicked', event);
  });
  await Flic.addListener('buttonHold', (event) => {
    console.log('Button was held down', event);
  });
};
```

### Forget a button

```
import { Flic } from '@capawesome/capacitor-flic';

const forgetButton = async (id: string) => {
  await Flic.forgetButtonById({ id });
};
```

### Check and request permissions

```
import { Flic } from '@capawesome/capacitor-flic';

const checkPermissions = async () => {
  const permissionStatus = await Flic.checkPermissions();
  return permissionStatus;
};

const requestPermissions = async () => {
  const permissionStatus = await Flic.requestPermissions();
  return permissionStatus;
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`connectButtonById(...)`](#connectbuttonbyid)
- [`disconnectButtonById(...)`](#disconnectbuttonbyid)
- [`forgetButtonById(...)`](#forgetbuttonbyid)
- [`getButtons()`](#getbuttons)
- [`initialize(...)`](#initialize)
- [`requestPermissions()`](#requestpermissions)
- [`startScan()`](#startscan)
- [`stopScan()`](#stopscan)
- [`addListener('buttonConnected', ...)`](#addlistenerbuttonconnected-)
- [`addListener('buttonConnectionFailed', ...)`](#addlistenerbuttonconnectionfailed-)
- [`addListener('buttonDisconnected', ...)`](#addlistenerbuttondisconnected-)
- [`addListener('buttonDoubleClick', ...)`](#addlistenerbuttondoubleclick-)
- [`addListener('buttonDown', ...)`](#addlistenerbuttondown-)
- [`addListener('buttonHold', ...)`](#addlistenerbuttonhold-)
- [`addListener('buttonReady', ...)`](#addlistenerbuttonready-)
- [`addListener('buttonSingleClick', ...)`](#addlistenerbuttonsingleclick-)
- [`addListener('buttonUnpaired', ...)`](#addlistenerbuttonunpaired-)
- [`addListener('buttonUp', ...)`](#addlistenerbuttonup-)
- [`addListener('scanStatusChanged', ...)`](#addlistenerscanstatuschanged-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the status of the permissions that are required to use Flic buttons.

On iOS, the Bluetooth permission is requested when `initialize(...)` is called.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### connectButtonById(...)

```
connectButtonById(options: ConnectButtonByIdOptions) => Promise<void>
```

Connect a button.

The returned promise resolves immediately. The connection is established as soon as the button is available and does not time out. Listen to the `buttonConnected` and `buttonReady` events to know when the button is ready to be used.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `ConnectButtonByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### disconnectButtonById(...)

```
disconnectButtonById(options: DisconnectButtonByIdOptions) => Promise<void>
```

Disconnect a button or cancel a pending connection.

Only available on Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `DisconnectButtonByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### forgetButtonById(...)

```
forgetButtonById(options: ForgetButtonByIdOptions) => Promise<void>
```

Forget a button.

This removes the pairing with the button. To use the button again, it must be paired again using `startScan()`.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `ForgetButtonByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getButtons()

```
getButtons() => Promise<GetButtonsResult>
```

Get all buttons that are currently paired with the app.

Only available on Android and iOS.

**Returns:** `Promise<GetButtonsResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

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

Initialize the plugin.

This method must be called before any other method. It is recommended to call this method as soon as possible after the app has launched to minimize the delay of any pending button events.

On iOS, this method triggers the Bluetooth permission prompt if the permission has not yet been granted.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the permissions that are required to use Flic buttons.

On iOS, this method only returns the current permission status since the Bluetooth permission is requested when `initialize(...)` is called.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### startScan()

```
startScan() => Promise<StartScanResult>
```

Start scanning for new buttons to pair.

To pair a button, press and hold it for at least 6 seconds while scanning. The returned promise resolves with the paired button once the pairing has completed. Listen to the `scanStatusChanged` event to keep the user informed about the scan progress.

Only one scan can be running at a time.

Only available on Android and iOS.

**Returns:** `Promise<StartScanResult>`

**Since:** 0.1.0

______________________________________________________________________

### stopScan()

```
stopScan() => Promise<void>
```

Stop an ongoing scan.

This rejects the pending `startScan()` call.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonConnected', ...)

```
addListener(eventName: 'buttonConnected', listenerFunc: (event: ButtonConnectedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button establishes a Bluetooth connection.

The button is not ready to be used until the `buttonReady` event is emitted.

Only available on Android and iOS.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'buttonConnected'`                     |
| **`listenerFunc`** | `(event: ButtonConnectedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonConnectionFailed', ...)

```
addListener(eventName: 'buttonConnectionFailed', listenerFunc: (event: ButtonConnectionFailedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a connection attempt to a button fails.

Only available on Android and iOS.

| Param              | Type                                           |
| ------------------ | ---------------------------------------------- |
| **`eventName`**    | `'buttonConnectionFailed'`                     |
| **`listenerFunc`** | `(event: ButtonConnectionFailedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonDisconnected', ...)

```
addListener(eventName: 'buttonDisconnected', listenerFunc: (event: ButtonDisconnectedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the Bluetooth connection with a button is lost.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'buttonDisconnected'`                     |
| **`listenerFunc`** | `(event: ButtonDisconnectedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonDoubleClick', ...)

```
addListener(eventName: 'buttonDoubleClick', listenerFunc: (event: ButtonEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button is double clicked.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'buttonDoubleClick'`          |
| **`listenerFunc`** | `(event: ButtonEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonDown', ...)

```
addListener(eventName: 'buttonDown', listenerFunc: (event: ButtonEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button is pressed down.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'buttonDown'`                 |
| **`listenerFunc`** | `(event: ButtonEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonHold', ...)

```
addListener(eventName: 'buttonHold', listenerFunc: (event: ButtonEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button is held down.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'buttonHold'`                 |
| **`listenerFunc`** | `(event: ButtonEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonReady', ...)

```
addListener(eventName: 'buttonReady', listenerFunc: (event: ButtonReadyEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button has been cryptographically verified after a connection and is ready to be used.

Only available on Android and iOS.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'buttonReady'`                     |
| **`listenerFunc`** | `(event: ButtonReadyEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonSingleClick', ...)

```
addListener(eventName: 'buttonSingleClick', listenerFunc: (event: ButtonEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button is clicked once.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'buttonSingleClick'`          |
| **`listenerFunc`** | `(event: ButtonEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonUnpaired', ...)

```
addListener(eventName: 'buttonUnpaired', listenerFunc: (event: ButtonUnpairedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the pairing with a button is no longer valid, for example because the button has been factory reset. In this case, the button must be forgotten using `forgetButtonById(...)` and then paired again.

Only available on Android and iOS.

| Param              | Type                                   |
| ------------------ | -------------------------------------- |
| **`eventName`**    | `'buttonUnpaired'`                     |
| **`listenerFunc`** | `(event: ButtonUnpairedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('buttonUp', ...)

```
addListener(eventName: 'buttonUp', listenerFunc: (event: ButtonEvent) => void) => Promise<PluginListenerHandle>
```

Called when a button is released.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'buttonUp'`                   |
| **`listenerFunc`** | `(event: ButtonEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('scanStatusChanged', ...)

```
addListener(eventName: 'scanStatusChanged', listenerFunc: (event: ScanStatusChangedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the status of an ongoing scan changes.

Only available on Android and iOS.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'scanStatusChanged'`                     |
| **`listenerFunc`** | `(event: ScanStatusChangedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop                   | Type              | Description                                                                                                                        | Since |
| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bluetooth`**        | `PermissionState` | The permission state of the Bluetooth permission. Only available on iOS.                                                           | 0.1.0 |
| **`bluetoothConnect`** | `PermissionState` | The permission state of the `BLUETOOTH_CONNECT` permission. Only required on Android 12 and later. Only available on Android.      | 0.1.0 |
| **`bluetoothScan`**    | `PermissionState` | The permission state of the `BLUETOOTH_SCAN` permission. Only required on Android 12 and later. Only available on Android.         | 0.1.0 |
| **`location`**         | `PermissionState` | The permission state of the `ACCESS_FINE_LOCATION` permission. Only required on Android 11 and earlier. Only available on Android. | 0.1.0 |

#### ConnectButtonByIdOptions

| Prop     | Type     | Description                   | Since |
| -------- | -------- | ----------------------------- | ----- |
| **`id`** | `string` | The identifier of the button. | 0.1.0 |

#### DisconnectButtonByIdOptions

| Prop     | Type     | Description                   | Since |
| -------- | -------- | ----------------------------- | ----- |
| **`id`** | `string` | The identifier of the button. | 0.1.0 |

#### ForgetButtonByIdOptions

| Prop     | Type     | Description                   | Since |
| -------- | -------- | ----------------------------- | ----- |
| **`id`** | `string` | The identifier of the button. | 0.1.0 |

#### GetButtonsResult

| Prop          | Type       | Description                                         | Since |
| ------------- | ---------- | --------------------------------------------------- | ----- |
| **`buttons`** | `Button[]` | The buttons that are currently paired with the app. | 0.1.0 |

#### Button

| Prop                  | Type                    | Description                                                                                                                                                                                                                                | Since |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`batteryVoltage`**  | `number`                | The last known battery voltage of the button in volts. If no battery sample has been taken yet, this property is not available. It is recommended to show a "change the battery soon" hint in your app once the voltage goes below `2.65`. | 0.1.0 |
| **`connectionState`** | `ButtonConnectionState` | The connection state of the button.                                                                                                                                                                                                        | 0.1.0 |
| **`firmwareVersion`** | `number`                | The revision of the firmware currently running on the button.                                                                                                                                                                              | 0.1.0 |
| **`id`**              | `string`                | The identifier of the button on this device. On Android, this is the Bluetooth address of the button. On iOS, this is an identifier that is guaranteed to be the same for each button paired to a particular device.                       | 0.1.0 |
| **`isReady`**         | `boolean`               | Whether or not the button has been cryptographically verified after a connection and is ready to be used.                                                                                                                                  | 0.1.0 |
| **`isUnpaired`**      | `boolean`               | Whether or not the pairing with the button is no longer valid, for example because the button has been factory reset. In this case, the button must be forgotten using `forgetButtonById(...)` and then paired again.                      | 0.1.0 |
| **`name`**            | `string`                | The human readable name of the button that the user may change in the official Flic app.                                                                                                                                                   | 0.1.0 |
| **`pressCount`**      | `number`                | The number of times the button has been clicked since it last booted.                                                                                                                                                                      | 0.1.0 |
| **`serialNumber`**    | `string`                | The serial number of the button that is printed on the backside of the button inside the battery hatch.                                                                                                                                    | 0.1.0 |
| **`uuid`**            | `string`                | The unique identifier of the button that is the same across devices and apps.                                                                                                                                                              | 0.1.0 |

#### InitializeOptions

| Prop                | Type      | Description                                                                                                                                                                                                              | Default | Since |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`iosBackground`** | `boolean` | Whether or not you intend to use the buttons while the app is in the background. If set to `true`, the `Uses Bluetooth LE accessories` background mode must be enabled in the app's capabilities. Only available on iOS. | `false` | 0.1.0 |

#### StartScanResult

| Prop         | Type     | Description                 | Since |
| ------------ | -------- | --------------------------- | ----- |
| **`button`** | `Button` | The button that was paired. | 0.1.0 |

#### PluginListenerHandle

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

#### ButtonConnectedEvent

| Prop           | Type     | Description                   | Since |
| -------------- | -------- | ----------------------------- | ----- |
| **`buttonId`** | `string` | The identifier of the button. | 0.1.0 |

#### ButtonConnectionFailedEvent

| Prop           | Type     | Description                                                   | Since |
| -------------- | -------- | ------------------------------------------------------------- | ----- |
| **`buttonId`** | `string` | The identifier of the button.                                 | 0.1.0 |
| **`message`**  | `string` | The message that describes why the connection attempt failed. | 0.1.0 |

#### ButtonDisconnectedEvent

| Prop           | Type     | Description                   | Since |
| -------------- | -------- | ----------------------------- | ----- |
| **`buttonId`** | `string` | The identifier of the button. | 0.1.0 |

#### ButtonEvent

| Prop            | Type      | Description                                                                              | Since |
| --------------- | --------- | ---------------------------------------------------------------------------------------- | ----- |
| **`buttonId`**  | `string`  | The identifier of the button.                                                            | 0.1.0 |
| **`timestamp`** | `number`  | The timestamp of the event in milliseconds since the Unix epoch.                         | 0.1.0 |
| **`wasQueued`** | `boolean` | Whether or not the event was queued because it occurred before the button was connected. | 0.1.0 |

#### ButtonReadyEvent

| Prop           | Type     | Description                   | Since |
| -------------- | -------- | ----------------------------- | ----- |
| **`buttonId`** | `string` | The identifier of the button. | 0.1.0 |

#### ButtonUnpairedEvent

| Prop           | Type     | Description                   | Since |
| -------------- | -------- | ----------------------------- | ----- |
| **`buttonId`** | `string` | The identifier of the button. | 0.1.0 |

#### ScanStatusChangedEvent

| Prop         | Type         | Description             | Since |
| ------------ | ------------ | ----------------------- | ----- |
| **`status`** | `ScanStatus` | The status of the scan. | 0.1.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### ButtonConnectionState

| Members             | Value             | Description                                                                                                          | Since |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Connected`**     | `'CONNECTED'`     | The button is connected.                                                                                             | 0.1.0 |
| **`Connecting`**    | `'CONNECTING'`    | The button is disconnected but a pending connection is set. The button will connect as soon as it becomes available. | 0.1.0 |
| **`Disconnected`**  | `'DISCONNECTED'`  | The button is disconnected and no pending connection is set.                                                         | 0.1.0 |
| **`Disconnecting`** | `'DISCONNECTING'` | The button is connected but is attempting to disconnect. Only available on iOS.                                      | 0.1.0 |

#### ScanStatus

| Members                      | Value                          | Description                                                                            | Since |
| ---------------------------- | ------------------------------ | -------------------------------------------------------------------------------------- | ----- |
| **`AskToAcceptPairRequest`** | `'ASK_TO_ACCEPT_PAIR_REQUEST'` | The user must accept the system pairing dialog to continue. Only available on Android. | 0.1.0 |
| **`Connected`**              | `'CONNECTED'`                  | A button was found and a connection is being established.                              | 0.1.0 |
| **`Discovered`**             | `'DISCOVERED'`                 | A button was discovered.                                                               | 0.1.0 |
| **`Verified`**               | `'VERIFIED'`                   | The button has been cryptographically verified. Only available on iOS.                 | 0.1.0 |

## FAQ

### Which Flic buttons are supported?

The plugin supports Flic 2 buttons. For the Flic Duo, only the events of the big button are currently delivered.

### Does the plugin receive button events while the app is in the background?

On Android, events are delivered as long as the app process is alive. Consider using the [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/) plugin to keep the app process alive. On iOS, enable the `Uses Bluetooth LE accessories` background mode and call `initialize(...)` with the `iosBackground` option set to `true` (see [Installation](#installation)).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Keep the app process alive to receive button events in the background on Android.
- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with other Bluetooth Low Energy devices.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/flic/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/flic/LICENSE).

The bundled [flic2lib](https://github.com/50ButtonsEach/flic2lib-ios) binary is distributed under its own license from Shortcut Labs AB (see [flic2lib-LICENCE.txt](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/flic/ios/flic2lib-LICENCE.txt)).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Shortcut Labs AB or any of its affiliates or subsidiaries. "Flic" is a trademark of Shortcut Labs AB. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Formbricks Plugin

Unofficial Capacitor plugin for [Formbricks](https://formbricks.com/).[1](#fn:1)

## Use Cases

The Formbricks plugin is typically used to collect user feedback directly in your app, for example:

- **In-app surveys**: Track actions like a button press to trigger Formbricks surveys at the right moment.
- **Personalized feedback**: Identify users with a user ID to connect survey responses to specific users.
- **Targeted surveys**: Set user attributes such as plan or tier to show surveys only to specific user segments.
- **Localized surveys**: Set the survey language to show surveys in the user's language.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-formbricks` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-formbricks @formbricks/js
npx cap sync
```

### Android

#### 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:

- `$formbricksAndroidVersion` version of `com.formbricks:android` (default: `1.2.0`)

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

#### Data Binding

The Formbricks Android SDK requires Data Binding to be enabled in your app's `build.gradle` file:

```
android {
    buildFeatures {
        dataBinding true
    }
}
```

### iOS

#### Minimum Deployment Target

If you are using **Swift Package Manager**, make sure that your iOS deployment target is set to at least `16.6` in your Xcode project settings (usually in `ios/App/App.xcodeproj`):

```
-IPHONEOS_DEPLOYMENT_TARGET = 15.0
+IPHONEOS_DEPLOYMENT_TARGET = 16.6
```

If you are using **CocoaPods**, make sure that your iOS deployment target is set to at least `16.6` in your `Podfile`:

```
platform :ios, '16.6'
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to set up the SDK, identify the user, set user attributes, set the survey language, track an action, and log out the user.

### Set up the SDK

Set up the Formbricks SDK with the URL of your Formbricks instance and the environment ID of your Formbricks project. This method must be called before any other method:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const setup = async () => {
  await Formbricks.setup({
    appUrl: 'https://app.formbricks.com',
    environmentId: 'YOUR_ENVIRONMENT_ID',
  });
};
```

### Identify the user

Set the user ID of the current user to connect survey responses to that user:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const setUserId = async () => {
  await Formbricks.setUserId({
    userId: 'user-123',
  });
};
```

### Set user attributes

Set a single attribute with `setAttribute(...)` or multiple attributes at once with `setAttributes(...)`, for example to target surveys to specific user segments:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const setAttribute = async () => {
  await Formbricks.setAttribute({
    key: 'plan',
    value: 'pro',
  });
};

const setAttributes = async () => {
  await Formbricks.setAttributes({
    attributes: {
      plan: 'pro',
      tier: 'gold',
    },
  });
};
```

### Set the survey language

Set the language in which surveys are displayed:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const setLanguage = async () => {
  await Formbricks.setLanguage({
    language: 'de',
  });
};
```

### Track an action

Track an action that may trigger a survey:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const track = async () => {
  await Formbricks.track({
    action: 'button_pressed',
  });
};
```

### Log out the user

Log out the current user and clear all attributes:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

const logout = async () => {
  await Formbricks.logout();
};
```

## API

- [`logout()`](#logout)
- [`setAttribute(...)`](#setattribute)
- [`setAttributes(...)`](#setattributes)
- [`setLanguage(...)`](#setlanguage)
- [`setUserId(...)`](#setuserid)
- [`setup(...)`](#setup)
- [`track(...)`](#track)
- [Interfaces](#interfaces)

### logout()

```
logout() => Promise<void>
```

Log out the current user and clear all attributes.

**Since:** 0.1.0

______________________________________________________________________

### setAttribute(...)

```
setAttribute(options: SetAttributeOptions) => Promise<void>
```

Set a single user attribute.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SetAttributeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setAttributes(...)

```
setAttributes(options: SetAttributesOptions) => Promise<void>
```

Set multiple user attributes at once.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetAttributesOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setLanguage(...)

```
setLanguage(options: SetLanguageOptions) => Promise<void>
```

Set the survey language.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetLanguageOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUserId(...)

```
setUserId(options: SetUserIdOptions) => Promise<void>
```

Set the user ID of the current user.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetUserIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setup(...)

```
setup(options: SetupOptions) => Promise<void>
```

Setup the Formbricks SDK with the provided options.

**Attention**: This method must be called before any other method.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `SetupOptions` |

**Since:** 0.1.0

______________________________________________________________________

### track(...)

```
track(options: TrackOptions) => Promise<void>
```

Track an action that may trigger a survey.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `TrackOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### SetAttributeOptions

| Prop        | Type     | Description                 | Since |
| ----------- | -------- | --------------------------- | ----- |
| **`key`**   | `string` | The name of the attribute.  | 0.1.0 |
| **`value`** | `string` | The value of the attribute. | 0.1.0 |

#### SetAttributesOptions

| Prop             | Type                         | Description            | Since |
| ---------------- | ---------------------------- | ---------------------- | ----- |
| **`attributes`** | `{ [key: string]: string; }` | The attributes to set. | 0.1.0 |

#### SetLanguageOptions

| Prop           | Type     | Description                                           | Since |
| -------------- | -------- | ----------------------------------------------------- | ----- |
| **`language`** | `string` | The language code of the survey language (e.g. `de`). | 0.1.0 |

#### SetUserIdOptions

| Prop         | Type     | Description                      | Since |
| ------------ | -------- | -------------------------------- | ----- |
| **`userId`** | `string` | The user ID of the current user. | 0.1.0 |

#### SetupOptions

| Prop                | Type     | Description                                    | Since |
| ------------------- | -------- | ---------------------------------------------- | ----- |
| **`appUrl`**        | `string` | The URL of your Formbricks instance.           | 0.1.0 |
| **`environmentId`** | `string` | The environment ID of your Formbricks project. | 0.1.0 |

#### TrackOptions

| Prop         | Type     | Description                      | Since |
| ------------ | -------- | -------------------------------- | ----- |
| **`action`** | `string` | The name of the action to track. | 0.1.0 |

## FAQ

### Can I use this plugin with a self-hosted Formbricks instance?

Yes, the `appUrl` option of the `setup(...)` method takes the URL of your Formbricks instance. Simply pass the URL of your self-hosted instance instead of `https://app.formbricks.com`.

### Why is no survey shown after calling `track`?

Make sure that `setup(...)` has been called first, since it must be called before any other method. Also note that `track(...)` only tracks an action that *may* trigger a survey. Whether a survey is actually shown depends on how the survey is configured in your Formbricks project.

### Why does my iOS build fail after installing the plugin?

The Formbricks iOS SDK requires an iOS deployment target of at least `16.6`. Make sure that your deployment target is set accordingly in your Xcode project settings or `Podfile`, as described in the [Installation](#installation) section.

### Why does my Android build fail after installing the plugin?

The Formbricks Android SDK requires Data Binding to be enabled in your app's `build.gradle` file. See the [Installation](#installation) section for the required configuration.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/): Let users submit app store reviews and ratings.
- [Grafana Faro](https://capawesome.io/docs/sdks/capacitor/grafana-faro/): Unofficial Capacitor plugin for Grafana Faro.
- [Intercom](https://capawesome.io/docs/sdks/capacitor/intercom/): Unofficial Capacitor plugin for the Intercom live chat and customer support platform.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for PostHog.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/formbricks/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/formbricks/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Formbricks GmbH or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Geocoder Plugin

Capacitor plugin for handling geocoding and reverse geocoding.

## Features

The Capacitor Geocoder plugin is one of the most complete geocoding solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 📍 **Geocoding**: Convert addresses into geographic coordinates.
- 🗺️ **Reverse Geocoding**: Convert geographic coordinates into human-readable addresses.
- 🌐 **Multiple Providers**: Support for Google Maps and OpenStreetMap on Web.
- 🌍 **Localization**: Customize the locale for geocoding requests.
- 🔢 **Configurable Results**: Limit the number of addresses returned in reverse geocoding operations.
- 🛠️ **Native APIs**: Uses platform-native geocoding services on Android and iOS for reliable and accurate results.
- 🤝 **Compatibility**: Works alongside the [Compass](https://capawesome.io/docs/sdks/capacitor/compass/) and [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Geocoder plugin is typically used whenever an app needs to translate between addresses and coordinates, for example:

- **Address search**: Convert a user-entered address into geographic coordinates to display the location on a map.
- **Location labeling**: Show a human-readable address for given coordinates, for example the user's current position.
- **Address forms**: Prefill address fields such as postal code, country, or administrative area based on coordinates.
- **Localized results**: Return addresses in the user's preferred language using the `locale` option.

## Compatibility

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

## Demo

| Android | iOS | Web |
| ------- | --- | --- |
|         |     |     |

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-geocoder` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-geocoder universal-geocoder
npx cap sync
```

## Usage

The following examples show how to convert an address into coordinates and how to convert coordinates back into an address.

### Convert an address into coordinates

Use the `geocode(...)` method to translate a human-readable address into geographic coordinates, for example to display the location on a map:

```
import { Geocoder } from '@capawesome-team/capacitor-geocoder';

const geocode = async () => {
  const result = await Geocoder.geocode({
    address: '1600 Amphitheatre Parkway, Mountain View, CA',
  });
  console.log('Geocode result:', result);
};
```

### Convert coordinates into an address

Use the `geodecode(...)` method to translate geographic coordinates into one or more human-readable addresses. The number of returned addresses can be limited with the `limit` option:

```
import { Geocoder } from '@capawesome-team/capacitor-geocoder';

const geodecode = async () => {
  const result = await Geocoder.geodecode({
    latitude: 37.422,
    longitude: -122.084,
  });
  console.log('Geodecode result:', result);
};
```

## API

- [`geocode(...)`](#geocode)
- [`geodecode(...)`](#geodecode)
- [Interfaces](#interfaces)

### geocode(...)

```
geocode(options: GeocodeOptions) => Promise<GeocodeResult>
```

Translate an address into geographic coordinates.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `GeocodeOptions` |

**Returns:** `Promise<GeocodeResult>`

**Since:** 0.0.1

______________________________________________________________________

### geodecode(...)

```
geodecode(options: GeodecodeOptions) => Promise<GeodecodeResult>
```

Translate geographic coordinates into a human-readable address.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GeodecodeOptions` |

**Returns:** `Promise<GeodecodeResult>`

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### GeocodeResult

| Prop            | Type     | Description                             | Since |
| --------------- | -------- | --------------------------------------- | ----- |
| **`latitude`**  | `number` | The latitude of the geocoded location.  | 0.0.1 |
| **`longitude`** | `number` | The longitude of the geocoded location. | 0.0.1 |

#### GeocodeOptions

| Prop               | Type           | Description                                                                                                 | Default                                                               | Since              |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ |
| **`address`**      | `string`       | The address to geocode.                                                                                     |                                                                       | 0.0.1              |
| **`locale`**       | `string`       | The locale (BCP 47 language tag) to use for the geocoding request. By default, the device's locale is used. |                                                                       | 0.0.1              |
| **`webApiKey`**    | `string`       | The API key to use for the geocoding service. Only available on Web.                                        |                                                                       | 0.0.1              |
| **`webProvider`**  | \`'googlemaps' | 'openstreetmaps'\`                                                                                          | The provider to use for the geocoding service. Only available on Web. | `'openstreetmaps'` |
| **`webUserAgent`** | `string`       | The User-Agent identifying your application. Only available on the web.                                     |                                                                       | 0.0.1              |

#### GeodecodeResult

| Prop            | Type        | Description                                                                                                                | Since |
| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`addresses`** | `Address[]` | The list of addresses that match the given coordinates. The number of addresses returned is limited by the `limit` option. | 0.0.1 |

#### Address

| Prop               | Type       | Description                                                      | Since |
| ------------------ | ---------- | ---------------------------------------------------------------- | ----- |
| **`adminArea`**    | `string`   | The administrative area (e.g. state or province) of the address. | 0.0.1 |
| **`addressLines`** | `string[]` | The lines of the address.                                        | 0.0.1 |
| **`countryCode`**  | `string`   | The country code of the address.                                 | 0.0.1 |
| **`countryName`**  | `string`   | The name of the country.                                         | 0.0.1 |
| **`phoneNumber`**  | `string`   | The phone number of the address.                                 | 0.0.1 |
| **`postalCode`**   | `string`   | The postal code of the address.                                  | 0.0.1 |
| **`subAdminArea`** | `string`   | The sub-administrative area (e.g. county) of the address.        | 0.0.1 |
| **`url`**          | `string`   | The URL of the address.                                          | 0.0.1 |

#### GeodecodeOptions

| Prop               | Type           | Description                                                                                                                                                                                                                                                                                              | Default                                                               | Since              |
| ------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ |
| **`latitude`**     | `number`       | The latitude of the location to reverse geocode.                                                                                                                                                                                                                                                         |                                                                       | 0.0.1              |
| **`limit`**        | `number`       | The maximum number of results to return.                                                                                                                                                                                                                                                                 | `5`                                                                   | 0.0.1              |
| **`longitude`**    | `number`       | The longitude of the location to reverse geocode.                                                                                                                                                                                                                                                        |                                                                       | 0.0.1              |
| **`webApiKey`**    | `string`       | The API key to use for the geocoding service. Only available on Web.                                                                                                                                                                                                                                     |                                                                       | 0.0.1              |
| **`webProvider`**  | \`'googlemaps' | 'openstreetmaps'\`                                                                                                                                                                                                                                                                                       | The provider to use for the geocoding service. Only available on Web. | `'openstreetmaps'` |
| **`webUserAgent`** | `string`       | The User-Agent identifying your application. Only needed if `webProvider` is set to `openstreetmaps` which uses the Nominatim service (see https://operations.osmfoundation.org/policies/nominatim/). The goal is to be able to limit the number of requests per application. Only available on the web. |                                                                       | 0.0.1              |

## FAQ

### What is the difference between geocoding and reverse geocoding?

Geocoding translates a human-readable address into geographic coordinates, which is what the `geocode` method does. Reverse geocoding is the opposite: the `geodecode` method translates a latitude and longitude into one or more human-readable addresses.

### Which geocoding services does the plugin use?

On Android and iOS, the plugin uses the platform-native geocoding services for reliable and accurate results. On the Web, you can choose between Google Maps and OpenStreetMap using the `webProvider` option, with OpenStreetMap being the default.

### Do I need an API key to use this plugin?

No API key is required on Android and iOS since the plugin uses the platform-native geocoding services. On the Web, you can provide an API key for the geocoding service using the `webApiKey` option. When using the default OpenStreetMap provider, you should also set the `webUserAgent` option to identify your application, as required by the [Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/).

### How can I limit the number of addresses returned by a reverse geocoding request?

Use the `limit` option of the `geodecode` method. By default, a maximum of 5 addresses is returned for the given coordinates.

### Can I get results in a specific language?

Yes, both methods accept a `locale` option that takes a BCP 47 language tag. If no locale is provided, the device's locale is used.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device compass heading.
- [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/): Launch navigation apps with turn-by-turn directions.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/LICENSE).

# Capacitor Geofences Plugin

Capacitor plugin for monitoring OS-managed geofences (region monitoring) on Android and iOS. Detects enter, exit and dwell transitions even while the app is in the background or terminated.

## Features

The Capacitor Geofences plugin lets your app react when a device enters or leaves a geographic region, using the battery-efficient region monitoring built into the operating system. Here are some of the key features:

- 🌍 **OS-Managed Regions**: Uses `GeofencingClient` on Android and `CLLocationManager` region monitoring on iOS, so transitions are detected by the system with minimal battery impact.
- 🔔 **Transition Events**: Get notified about enter, exit and (on Android) dwell transitions.
- 💀 **Killed-App Delivery**: Transitions that occur while the app is terminated are stored in a durable on-device queue and can trigger a native local notification.
- 📥 **Durable Queue**: Read the queue from JavaScript with keyset pagination and acknowledge what you processed, so nothing is lost between two app starts.
- ☁️ **HTTP Upload**: Upload transitions to your own server with automatic retries and at-least-once delivery — even while the app is in the background or terminated.
- 🔁 **Auto Re-Registration**: On Android, geofences are automatically re-registered after a device reboot or an app update.
- 🔒 **Public APIs Only**: Built exclusively on public platform APIs, so it is safe for App Review and resilient to OS updates.
- 🤝 **Compatibility**: Works hand in hand with the [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) plugin for continuous location tracking.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Geofences plugin is typically used whenever an app needs to react when a device enters or leaves a specific area, for example:

- **Location-based reminders**: Notify users when they arrive at or leave a place, for example a store, an office, or their home.
- **Attendance and check-ins**: Check users in or out automatically when they enter or leave a site, using dwell transitions on Android to confirm that they actually stayed.
- **Proximity marketing**: Display a native local notification with an offer when a customer walks near one of your branches, even while the app is terminated.
- **Field service and logistics**: Record arrivals at and departures from customer sites or depots without draining the battery through continuous tracking.
- **Safety zones**: Alert caregivers or fleet managers when a person or vehicle leaves a defined safe area.
- **Context-aware apps**: Adapt the app to the user's surroundings, for example by switching to a venue-specific view once the user is on site.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.3.x          | >=8.x.x           | Active support |
| 0.2.x          | >=8.x.x           | Deprecated     |
| 0.1.x          | >=8.x.x           | Deprecated     |

## Guides

- [Announcing the Capacitor Geofences Plugin](https://capawesome.io/blog/announcing-the-capacitor-geofences-plugin/): Monitor OS-managed regions on Android and iOS and get enter, exit, and dwell events, even after the app is killed.
- [Why Are Your Geofences Not Triggering on iOS?](https://capawesome.io/blog/why-are-your-geofences-not-triggering-on-ios/): The iOS threshold rule, the already-inside case, permission levels, radius and reboot behavior, and how the queue preserves transitions.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-geofences` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-geofences
npx cap sync
```

### Android

#### Permissions

The plugin already declares the `ACCESS_FINE_LOCATION`, `POST_NOTIFICATIONS` and `RECEIVE_BOOT_COMPLETED` permissions in its manifest.

Geofencing additionally requires the **background location** permission. For [Google Play policy](https://support.google.com/googleplay/android-developer/answer/9799150) reasons, this permission is **not** declared by the plugin and must be added to your app's `AndroidManifest.xml` before or after the `application` tag:

```
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

Starting with Android 10 (API level 29), the background location permission cannot be requested together with the foreground location permission. You must first request the foreground location permission and only afterwards request the background location permission (see [Check and request permissions](#check-and-request-permissions)).

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### Variables

If needed, you can define the following project variables in your app's `variables.gradle` file to change the default versions of the dependencies:

- `$androidxWorkVersion` version of `androidx.work:work-runtime` (default: `2.11.2`)
- `$playServicesLocationVersion` version of `com.google.android.gms:play-services-location` (default: `21.4.0`)

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

### iOS

#### Privacy Descriptions

Add the `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the location:

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>The app needs access to your location to monitor geofences.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>The app needs access to your location to monitor geofences while it is in the background.</string>
```

If the keys are missing, `addGeofences(...)` and `requestPermissions(...)` reject with a clear error message.

## Configuration

No configuration required for this plugin.

## Usage

The following examples are grouped into permissions, geofences, transitions and upload.

### Getting started

Request the required permissions, register a geofence and drain the transition queue whenever your app becomes active. The `geofenceTransition` event is a live feed that only fires while your app is running — the **queue is the durable record** of every transition, including the ones that were detected while the app was terminated. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const start = async () => {
  // 1. Request the foreground and afterwards the background location permission.
  let status = await Geofences.requestPermissions({ permissions: ['location'] });
  if (status.location !== 'granted') {
    return;
  }
  status = await Geofences.requestPermissions({
    permissions: ['backgroundLocation'],
  });
  if (status.backgroundLocation !== 'granted') {
    return;
  }
  // 2. Add the geofence to monitor.
  await Geofences.addGeofences({
    geofences: [{ latitude: 37.33182, longitude: -122.03118, radius: 200 }],
  });
  // 3. Drain the queue now and whenever the app becomes active again.
  await drainQueue();
  document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'visible') {
      drainQueue();
    }
  });
};

const drainQueue = async () => {
  let hasMore = true;
  while (hasMore) {
    const result = await Geofences.getQueuedTransitions({ limit: 1000 });
    if (!result.transitions.length) {
      break;
    }
    await persist(result.transitions);
    await Geofences.deleteQueuedTransitions({
      upToId: result.transitions[result.transitions.length - 1].id,
    });
    hasMore = result.hasMore;
  }
};
```

### Permissions

#### Check and request permissions

Geofencing requires the **Always** location authorization on iOS and the **background location** permission on Android. Because of the platform restrictions described in the [Installation](#installation) section, the permissions must be requested in two steps:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const checkPermissions = async () => {
  return Geofences.checkPermissions();
};

const requestPermissions = async () => {
  // Step 1: Request the foreground location permission.
  let status = await Geofences.requestPermissions({
    permissions: ['location'],
  });
  // Step 2: Request the background location permission.
  if (status.location === 'granted') {
    status = await Geofences.requestPermissions({
      permissions: ['backgroundLocation'],
    });
  }
  // Optionally: Request the notifications permission.
  await Geofences.requestPermissions({ permissions: ['notifications'] });
  return status;
};
```

#### Open the app settings

If a permission was permanently denied, send the user to the native app settings:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const openSettings = async () => {
  await Geofences.openSettings();
};
```

### Geofences

#### Add geofences

Add one or more circular regions to be monitored by the operating system. Optionally, provide a `notification` that is displayed natively when a transition is detected, which is especially useful while the app is terminated. On Android, an enter transition is triggered immediately if the device is already inside a geofence that was just added, while iOS only reports a transition once the device crosses the boundary. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const addGeofences = async () => {
  const { ids } = await Geofences.addGeofences({
    geofences: [
      {
        latitude: 37.33182,
        longitude: -122.03118,
        radius: 200,
        notification: {
          title: 'Welcome',
          text: 'You have entered the area.',
        },
      },
    ],
  });
  return ids;
};
```

#### Retrieve geofences

Retrieve all geofences that are currently being monitored. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const getGeofences = async () => {
  const { geofences } = await Geofences.getGeofences();
  return geofences;
};
```

#### Remove geofences

Remove specific geofences by their identifier or remove all of them at once. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const removeGeofences = async (ids: string[]) => {
  await Geofences.removeGeofences({ ids });
};

const removeAllGeofences = async () => {
  await Geofences.removeAllGeofences();
};
```

### Transitions

#### Listen for geofence transitions

Get notified when the device enters, exits, or (on Android) dwells inside a geofence. The event is a **live feed**: it is only delivered while your app is running and a listener is registered. Transitions that were detected while the app was in the background or terminated are **not** replayed — read them from the [queue](#read-the-queue) instead. Only available on Android and iOS:

```
import { Geofences, TransitionType } from '@capawesome-team/capacitor-geofences';

const addListener = async () => {
  await Geofences.addListener('geofenceTransition', (event) => {
    if (event.transition.type === TransitionType.Enter) {
      console.log(`Entered the geofence ${event.transition.geofenceId}.`);
    }
  });
};
```

#### Read the queue

Every transition is appended to a durable on-device queue, whether or not your app is running. Read the queue in pages, process the transitions and delete the ones you processed. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const drainQueue = async () => {
  let hasMore = true;
  while (hasMore) {
    const result = await Geofences.getQueuedTransitions({ limit: 1000 });
    if (!result.transitions.length) {
      break;
    }
    await persist(result.transitions);
    await Geofences.deleteQueuedTransitions({
      upToId: result.transitions[result.transitions.length - 1].id,
    });
    hasMore = result.hasMore;
  }
};
```

See [Queue](#queue) for the capacity, the identifiers and the delivery guarantees.

#### Configure the queue

The queue is disabled until you configure it and then holds `1000` transitions by default. Call `resetConfig()` to disable it again. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const configureQueue = async () => {
  await Geofences.setConfig({ maxSize: 5000 });
};
```

#### Inspect and clear the queue

Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const getQueueStatus = async () => {
  const { pendingCount, droppedCount, lastUploadedAt } =
    await Geofences.getQueueStatus();
  console.log(
    `${pendingCount} transitions pending, ${droppedCount} dropped, last upload: ${lastUploadedAt}`,
  );
};

const clearQueue = async () => {
  await Geofences.clearQueue();
};
```

#### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

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

### Upload

#### Configure the upload

Configure the plugin to upload every queued transition to your own server, even while the app is in the background or terminated. The configuration is persisted natively, so it only needs to be set once (e.g. after sign-in). Failed upload attempts are reported via the `uploadFailed` event. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const configureUpload = async () => {
  await Geofences.addListener('uploadFailed', (event) => {
    console.error('Upload failed: ', event.statusCode, event.message);
  });
  await Geofences.setConfig({
    url: 'https://api.example.com/transitions',
    headers: {
      Authorization: 'Bearer eyJhbGciOi...',
    },
    extras: {
      userId: 'abc',
    },
  });
};

const disableUpload = async () => {
  await Geofences.resetConfig();
};
```

**Attention**: `setConfig(...)` replaces the stored configuration entirely, so always pass every property you want to keep.

See [HTTP Upload](#http-upload) for the server contract and the response handling.

#### Trigger the upload

Upload the queued transitions right away instead of waiting for the next retry. Only available on Android and iOS:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const triggerUpload = async () => {
  await Geofences.triggerUpload();
};
```

## API

- [`addGeofences(...)`](#addgeofences)
- [`checkPermissions()`](#checkpermissions)
- [`clearQueue()`](#clearqueue)
- [`deleteQueuedTransitions(...)`](#deletequeuedtransitions)
- [`getConfig()`](#getconfig)
- [`getGeofences()`](#getgeofences)
- [`getQueuedTransitions(...)`](#getqueuedtransitions)
- [`getQueueStatus()`](#getqueuestatus)
- [`openSettings()`](#opensettings)
- [`removeAllGeofences()`](#removeallgeofences)
- [`removeGeofences(...)`](#removegeofences)
- [`requestPermissions(...)`](#requestpermissions)
- [`resetConfig()`](#resetconfig)
- [`setConfig(...)`](#setconfig)
- [`triggerUpload()`](#triggerupload)
- [`addListener('geofenceTransition', ...)`](#addlistenergeofencetransition-)
- [`addListener('uploadFailed', ...)`](#addlisteneruploadfailed-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### addGeofences(...)

```
addGeofences(options: AddGeofencesOptions) => Promise<AddGeofencesResult>
```

Add one or more geofences to be monitored.

On **Android**, an enter transition is triggered immediately if the device is already inside a geofence that was just added. On **iOS**, no transition is triggered until the device crosses the boundary of the geofence.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `AddGeofencesOptions` |

**Returns:** `Promise<AddGeofencesResult>`

**Since:** 0.0.1

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for the plugin.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### clearQueue()

```
clearQueue() => Promise<void>
```

Delete all transitions from the queue.

Use `deleteQueuedTransitions(...)` to only delete the transitions that have already been read.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### deleteQueuedTransitions(...)

```
deleteQueuedTransitions(options: DeleteQueuedTransitionsOptions) => Promise<void>
```

Delete all transitions from the queue up to and including the given identifier.

Call this method after the transitions returned by `getQueuedTransitions(...)` have been processed successfully.

Only available on Android and iOS.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `DeleteQueuedTransitionsOptions` |

**Since:** 0.2.0

______________________________________________________________________

### getConfig()

```
getConfig() => Promise<GetConfigResult>
```

Get the configuration that was last set via `setConfig(...)`.

Only the properties that were provided are returned, so the result can be spread into `setConfig(...)` to change a single property:

```
const config = await Geofences.getConfig();
await Geofences.setConfig({ ...config, maxSize: 5000 });
```

An empty object is returned if `setConfig(...)` has not been called yet.

Only available on Android and iOS.

**Returns:** `Promise<SetConfigOptions>`

**Since:** 0.2.0

______________________________________________________________________

### getGeofences()

```
getGeofences() => Promise<GetGeofencesResult>
```

Get all geofences that are currently being monitored.

Only available on Android and iOS.

**Returns:** `Promise<GetGeofencesResult>`

**Since:** 0.0.1

______________________________________________________________________

### getQueuedTransitions(...)

```
getQueuedTransitions(options?: GetQueuedTransitionsOptions | undefined) => Promise<GetQueuedTransitionsResult>
```

Get the transitions that are currently stored in the queue, oldest first.

The transitions remain in the queue until they are deleted via `deleteQueuedTransitions(...)` or `clearQueue()`.

Only available on Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `GetQueuedTransitionsOptions` |

**Returns:** `Promise<GetQueuedTransitionsResult>`

**Since:** 0.2.0

______________________________________________________________________

### getQueueStatus()

```
getQueueStatus() => Promise<GetQueueStatusResult>
```

Get the current status of the queue.

Only available on Android and iOS.

**Returns:** `Promise<GetQueueStatusResult>`

**Since:** 0.2.0

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Opens the native app settings page to allow the user to grant the app the required permissions.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### removeAllGeofences()

```
removeAllGeofences() => Promise<void>
```

Remove all geofences that are currently being monitored.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### removeGeofences(...)

```
removeGeofences(options: RemoveGeofencesOptions) => Promise<void>
```

Remove one or more geofences by their identifier.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `RemoveGeofencesOptions` |

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions for the plugin.

The `backgroundLocation` permission must be requested in a **second**, separate call after the `location` permission has been granted:

- On **Android 11+**, the user is taken to the location settings of the app where the `Allow all the time` option must be selected.
- On **iOS**, the operating system presents the upgrade prompt that asks the user to change the permission from `While Using the App` to `Always`.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### resetConfig()

```
resetConfig() => Promise<void>
```

Discard the configuration so that no transitions are stored or uploaded.

Transitions that are already queued are kept, use `clearQueue()` to discard them.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### setConfig(...)

```
setConfig(options: SetConfigOptions) => Promise<void>
```

Set the configuration of the transition queue and of the upload.

The configuration is persisted natively so that it keeps working when the operating system wakes your app without a web view.

Transitions are stored in the queue if `maxSize` or `url` is provided, and they are uploaded if `url` is provided. Use `resetConfig()` to stop storing and uploading transitions.

**This method replaces the whole configuration**, so every property you omit falls back to its default. `setConfig({ maxSize: 5000 })` therefore also stops the upload, because `url` is no longer set. Keep your configuration in one place and pass it whole:

```
await Geofences.setConfig({ maxSize: 5000, url });
```

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetConfigOptions` |

**Since:** 0.2.0

______________________________________________________________________

### triggerUpload()

```
triggerUpload() => Promise<void>
```

Immediately attempt to upload all queued transitions.

Any pending retry backoff is cancelled and a new upload attempt is started right away. The promise resolves as soon as the attempt has been scheduled, not when the transitions have been delivered.

The promise rejects if no `url` has been set via `setConfig(...)`.

Only available on Android and iOS.

**Since:** 0.2.0

______________________________________________________________________

### addListener('geofenceTransition', ...)

```
addListener(eventName: 'geofenceTransition', listenerFunc: (event: GeofenceTransitionEvent) => void) => Promise<PluginListenerHandle>
```

Called when a geofence transition (enter, exit or dwell) is detected.

This event is a live feed that is only delivered while a listener is registered. Transitions that occurred while the app was in the background or terminated are **not** replayed. Read them from the queue via `getQueuedTransitions(...)` instead.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'geofenceTransition'`                     |
| **`listenerFunc`** | `(event: GeofenceTransitionEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('uploadFailed', ...)

```
addListener(eventName: 'uploadFailed', listenerFunc: (event: UploadFailedEvent) => void) => Promise<PluginListenerHandle>
```

Called when an upload attempt of queued transitions fails.

The affected transitions remain in the queue and are retried automatically unless the server rejected them permanently.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'uploadFailed'`                     |
| **`listenerFunc`** | `(event: UploadFailedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### AddGeofencesResult

| Prop      | Type       | Description                                                                                          | Since |
| --------- | ---------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`ids`** | `string[]` | The identifiers of the added geofences. The order matches the order of the geofences in the request. | 0.0.1 |

#### AddGeofencesOptions

| Prop            | Type         | Description           | Since |
| --------------- | ------------ | --------------------- | ----- |
| **`geofences`** | `Geofence[]` | The geofences to add. | 0.0.1 |

#### Geofence

| Prop                        | Type                   | Description                                                                                                                                                         | Default | Since |
| --------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`androidLoiteringDelay`** | `number`               | The time in milliseconds the device must dwell inside the geofence before a dwell transition event is triggered. Only available on Android.                         |         | 0.0.1 |
| **`androidNotifyOnDwell`**  | `boolean`              | Whether a transition event should be triggered when the device dwells inside the geofence. Only available on Android.                                               | `false` | 0.0.1 |
| **`id`**                    | `string`               | A unique identifier for the geofence. If not provided, a random identifier (UUID) is generated and returned in the result of the `addGeofences(...)` method.        |         | 0.0.1 |
| **`latitude`**              | `number`               | The latitude of the center of the geofence in degrees.                                                                                                              |         | 0.0.1 |
| **`longitude`**             | `number`               | The longitude of the center of the geofence in degrees.                                                                                                             |         | 0.0.1 |
| **`radius`**                | `number`               | The radius of the geofence in meters. Apple recommends a radius of at least 200 meters, as smaller radii may not trigger transitions reliably.                      |         | 0.0.1 |
| **`notifyOnEnter`**         | `boolean`              | Whether a transition event should be triggered when the device enters the geofence.                                                                                 | `true`  | 0.0.1 |
| **`notifyOnExit`**          | `boolean`              | Whether a transition event should be triggered when the device exits the geofence.                                                                                  | `true`  | 0.0.1 |
| **`notification`**          | `GeofenceNotification` | A local notification to display natively when a transition for this geofence is detected. This is especially useful to notify the user while the app is terminated. |         | 0.0.1 |

#### GeofenceNotification

| Prop        | Type     | Description                        | Since |
| ----------- | -------- | ---------------------------------- | ----- |
| **`title`** | `string` | The title of the notification.     | 0.0.1 |
| **`text`**  | `string` | The body text of the notification. | 0.0.1 |

#### PermissionStatus

| Prop                     | Type              | Description                                                                                                                                                                        | Since |
| ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`location`**           | `PermissionState` | The permission state for using the location while the app is in use.                                                                                                               | 0.0.1 |
| **`backgroundLocation`** | `PermissionState` | The permission state for using the location while the app is in the background. This permission is required to monitor geofences while the app is in the background or terminated. | 0.0.1 |
| **`notifications`**      | `PermissionState` | The permission state for displaying local notifications on a transition.                                                                                                           | 0.0.1 |

#### DeleteQueuedTransitionsOptions

| Prop         | Type     | Description                                                                                                         | Since |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | ----- |
| **`upToId`** | `number` | The identifier of the newest transition to delete. All transitions with this identifier or a lower one are deleted. | 0.2.0 |

#### SetConfigOptions

| Prop          | Type                         | Description                                                                                                                                                                                                                                        | Default      | Since                                                                                                  |
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| **`extras`**  | \`{ \[key: string\]: string  | number                                                                                                                                                                                                                                             | boolean; }\` | Static metadata that is attached to every upload request as the `extras` property of the request body. |
| **`headers`** | `{ [key: string]: string; }` | Static HTTP headers that are sent with every upload request, for example for authorization.                                                                                                                                                        |              | 0.2.0                                                                                                  |
| **`maxSize`** | `number`                     | The maximum number of transitions that are stored in the queue. When the queue is full, the oldest transitions are dropped first. A stored transition occupies about `140` bytes, so the default of `1000` needs about `140` KB. Must be positive. | `1000`       | 0.2.0                                                                                                  |
| **`url`**     | `string`                     | The URL the transitions are uploaded to via HTTP `POST`. Providing this property enables the upload. Omit it to keep the transitions on the device only.                                                                                           |              | 0.2.0                                                                                                  |

#### GetGeofencesResult

| Prop            | Type         | Description                                       | Since |
| --------------- | ------------ | ------------------------------------------------- | ----- |
| **`geofences`** | `Geofence[]` | The geofences that are currently being monitored. | 0.0.1 |

#### GetQueuedTransitionsResult

| Prop              | Type                 | Description                                                          | Since |
| ----------------- | -------------------- | -------------------------------------------------------------------- | ----- |
| **`hasMore`**     | `boolean`            | Whether more transitions are stored in the queue than were returned. | 0.2.0 |
| **`transitions`** | `QueuedTransition[]` | The queued transitions, oldest first.                                | 0.2.0 |

#### QueuedTransition

| Prop     | Type     | Description                                                                                                | Since |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------- | ----- |
| **`id`** | `number` | The identifier of the transition in the queue. The identifier increases monotonically and is never reused. | 0.2.0 |

#### GetQueuedTransitionsOptions

| Prop          | Type     | Description                                                                                                                                    | Default | Since |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`afterId`** | `number` | Only return transitions with an identifier greater than this value. If not provided, the transitions are returned from the start of the queue. |         | 0.2.0 |
| **`limit`**   | `number` | The maximum number of transitions to return. Must be greater than `0`.                                                                         | `100`   | 0.2.0 |

#### GetQueueStatusResult

| Prop                 | Type     | Description                                                                                                                                                                             | Since                                                                                                                                                                                                                 |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`droppedCount`**   | `number` | The number of transitions that were dropped without being read since the queue was last cleared, for example because the queue was full. This counter is persisted across app restarts. | 0.2.0                                                                                                                                                                                                                 |
| **`lastUploadedAt`** | \`number | null\`                                                                                                                                                                                  | The time at which the last batch of transitions was uploaded successfully in milliseconds since the Unix epoch or `null` if no batch has been uploaded successfully yet. This value is persisted across app restarts. |
| **`pendingCount`**   | `number` | The number of transitions that are currently stored in the queue.                                                                                                                       | 0.2.0                                                                                                                                                                                                                 |

#### RemoveGeofencesOptions

| Prop      | Type       | Description                                 | Since |
| --------- | ---------- | ------------------------------------------- | ----- |
| **`ids`** | `string[]` | The identifiers of the geofences to remove. | 0.0.1 |

#### RequestPermissionsOptions

| Prop              | Type               | Description                 | Default                         | Since |
| ----------------- | ------------------ | --------------------------- | ------------------------------- | ----- |
| **`permissions`** | `PermissionType[]` | The permissions to request. | `['location', 'notifications']` | 0.0.1 |

#### PluginListenerHandle

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

#### GeofenceTransitionEvent

| Prop             | Type                 | Description              | Since |
| ---------------- | -------------------- | ------------------------ | ----- |
| **`transition`** | `GeofenceTransition` | The detected transition. | 0.2.0 |

#### GeofenceTransition

| Prop             | Type             | Description                                                       | Since                                                                                                                                                      |
| ---------------- | ---------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`geofenceId`** | `string`         | The identifier of the geofence that triggered the transition.     | 0.2.0                                                                                                                                                      |
| **`latitude`**   | \`number         | null\`                                                            | The latitude of the location that triggered the transition in degrees. On **iOS**, this is always `null` because the triggering location is not provided.  |
| **`longitude`**  | \`number         | null\`                                                            | The longitude of the location that triggered the transition in degrees. On **iOS**, this is always `null` because the triggering location is not provided. |
| **`timestamp`**  | `number`         | The time the transition was detected in milliseconds since epoch. | 0.2.0                                                                                                                                                      |
| **`type`**       | `TransitionType` | The type of the transition.                                       | 0.2.0                                                                                                                                                      |

#### UploadFailedEvent

| Prop             | Type     | Description                                                       | Since |
| ---------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`message`**    | `string` | The error message.                                                | 0.0.1 |
| **`statusCode`** | `number` | The HTTP status code of the response, if a response was received. | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### GetConfigResult

`SetConfigOptions`

#### PermissionType

`'location' | 'backgroundLocation' | 'notifications'`

### Enums

#### TransitionType

| Members     | Value     | Description                                                            | Since |
| ----------- | --------- | ---------------------------------------------------------------------- | ----- |
| **`Dwell`** | `'DWELL'` | The device has dwelled inside the geofence. Only available on Android. | 0.0.1 |
| **`Enter`** | `'ENTER'` | The device has entered the geofence.                                   | 0.0.1 |
| **`Exit`**  | `'EXIT'`  | The device has exited the geofence.                                    | 0.0.1 |

## Queue

Once the queue is enabled, every geofence transition is appended to it, whether or not your app is running. The queue is then the **single source of truth**: the `geofenceTransition` event is an ephemeral live feed that only fires while your app is running, so an app that only listens to the event misses every transition that was detected while it was terminated.

Read the queue with `getQueuedTransitions(...)` and acknowledge the transitions you processed with `deleteQueuedTransitions(...)`. Reading and deleting are two separate steps on purpose: a crash between reading and persisting must not lose a transition.

### Identifiers

Every queued transition carries a numeric `id` that increases monotonically and is never reused, even after the queue was cleared or the app was restarted. This makes it usable both for keyset pagination via `afterId` and for the inclusive prefix delete via `upToId`.

### Behavior

- **Persistence**: The queue is stored in the sandboxed app storage and survives app restarts, force-quits and device reboots.
- **Opt-in**: Nothing is stored until you call `setConfig(...)` with `maxSize` or `url`, and transitions detected before that are not stored. Call `resetConfig()` to disable it again; transitions that are already queued are kept until `clearQueue()`.
- **Capacity**: The queue holds at most `1000` transitions by default, which can be changed via `setConfig({ maxSize })`. If the queue is full, the **oldest** transitions are dropped first.
- **Observability**: The `droppedCount` property of `getQueueStatus()` counts the transitions that were dropped since the queue was last cleared. The counter is persisted across app restarts.
- **Duplicates**: A transition that is delivered via the `geofenceTransition` event while your app is running is also stored in the queue. Treat the queue as the source of truth to avoid processing it twice.

## HTTP Upload

The plugin can upload every queued transition to your own server without involving JavaScript. Transitions are uploaded to the configured URL and only deleted from the queue after the server has acknowledged them. Since the whole pipeline runs natively, it keeps working while the web view is suspended — and, unlike a watch session of the [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) plugin, even while the app is terminated.

**Attention**: The upload drains the same queue that `getQueuedTransitions(...)` reads. Transitions are stored once and deleted once, so a transition your app deletes with `deleteQueuedTransitions(...)` is never uploaded, and a transition the server acknowledged is no longer readable. Use either the upload or your own drain loop, not both.

### Options

Call `setConfig({ url })` to enable the upload pipeline. The configuration is persisted natively so that transitions can be uploaded when the operating system wakes your app without a web view, and it applies to every future transition until `resetConfig()` is called. Call it on every app start anyway: the stored copy is only a cache of your last call, and it is discarded whenever the plugin's configuration format changes in a future version. Queued transitions are never discarded with it:

```
import { Geofences } from '@capawesome-team/capacitor-geofences';

const configureUpload = async () => {
  await Geofences.setConfig({
    url: 'https://api.example.com/transitions',
    headers: {
      Authorization: 'Bearer eyJhbGciOi...',
    },
    extras: {
      userId: 'abc',
    },
  });
};
```

**Attention**: The configuration you pass replaces the stored one entirely. Every property you omit falls back to its default, so read the stored configuration with `getConfig()` first if you only want to change a single property.

To stop the upload but keep storing transitions, call `setConfig(...)` again without `url`:

```
const { url, ...config } = await Geofences.getConfig();
await Geofences.setConfig(config);
```

### Server Contract

Transitions are uploaded with an HTTP `POST` request and the `Content-Type: application/json; charset=utf-8` header. Your own `headers` are applied afterwards and may override it. The request body looks as follows:

```
{
  "transitions": [
    {
      "id": 42,
      "geofenceId": "2ca23ff9-b95d-4962-b64f-3e1efe6f2e7d",
      "type": "ENTER",
      "timestamp": 1723291200000,
      "latitude": 52.52,
      "longitude": 13.405
    }
  ],
  "extras": { "userId": "abc" }
}
```

Every entry of the `transitions` array is a [`QueuedTransition`](#queuedtransition) object whose `id` property is the identifier of the transition in the queue and whose `geofenceId` property is the identifier of the geofence. On iOS, `latitude` and `longitude` are always `null`. The `extras` property is omitted entirely if the `extras` option was not provided.

**Idempotency**: The `id` is unique per app installation, not globally. Transitions are delivered **at least once**, so the same transition may be uploaded more than once, for example if the acknowledgment of the server is lost on the way back. Deduplicate the transitions on the server by the `id` together with a device or user identifier from `extras` to make the upload idempotent.

### Response Handling

The response body is always ignored. Only the status code decides what happens to the uploaded transitions:

| Status Code                                        | Behavior                                                                                                          |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `2xx`                                              | The transitions are acknowledged and deleted from the queue.                                                      |
| `401`, `408`, `429`, `5xx`, network error, timeout | The transitions stay in the queue and are retried with an exponential backoff. A `uploadFailed` event is emitted. |
| Any other status code                              | The transitions are **dropped permanently without being uploaded again** and a `uploadFailed` event is emitted.   |

**Attention**: Transitions that the server rejects with any status code other than `2xx`, `401`, `408`, `429` or `5xx` (for example `400 Bad Request` or `422 Unprocessable Entity`) are deleted from the queue and **lost**. This is intentional: a permanently rejected upload must never block the queue forever. `401` is treated as retryable, because it usually means an expired token rather than an unacceptable upload — refresh the credentials with `setConfig(...)` and the queued transitions are uploaded afterwards. Make sure your endpoint answers with a retryable status code (e.g. `503`) if it is temporarily unable to accept transitions, and listen to the `uploadFailed` event to detect such drops. Dropped transitions are also counted in the `droppedCount` property of `getQueueStatus()`.

The request timeout is 30 seconds. On Android, retries are scheduled via WorkManager with an exponential backoff starting at 10 seconds, so they survive a process death and even a device reboot. On iOS, retries start with a delay of 5 seconds and double after every attempt up to a maximum of 10 minutes while the app is alive; pending transitions are also uploaded on the next app launch and whenever a new transition is detected. The backoff is reset whenever `setConfig({ url })` or `triggerUpload()` is called.

### Deliberately Not Supported

The following features are intentionally not part of the upload pipeline:

- **Network constraints**: Uploads cannot be restricted to Wi-Fi or unmetered networks.
- **Response processing**: The response body of the server is always ignored, so the server cannot send commands back to the device.
- **Encryption at rest**: The queue is not encrypted. It is stored in the sandboxed app storage of the operating system.

## FAQ

### When should I use this plugin instead of the Background Geolocation plugin?

Both plugins solve different problems and complement each other. The [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) plugin continuously tracks the device's location and streams position updates to your app, which is what you need when you want the actual location trail. This plugin monitors circular regions and only notifies your app when the device crosses a region boundary, which is much cheaper on battery and can even deliver transitions while your app is terminated. Use Background Geolocation when you need the location trail, and Geofences when you only care about entering or leaving specific areas.

### How is this plugin different from other similar plugins?

It uses the operating system's own region monitoring — `GeofencingClient` on Android and Core Location on iOS — so enter, exit and dwell transitions are detected with minimal battery impact, even while your app is in the background or terminated. Transitions that occur while the app is killed are stored in a durable queue your app drains on the next launch and can trigger a native local notification, and on Android geofences are automatically re-registered after a reboot or app update. It's all exposed through one fully typed, actively maintained API with dedicated support; if you need the full location trail rather than boundary crossings, continuous tracking fits better, but for reacting to specific areas efficiently, this plugin is purpose-built.

### Is geofencing available on the web?

No. All methods are only available on Android and iOS. On the web, they reject with an unimplemented error.

### How many geofences can I register?

Android allows up to 100 geofences per app, iOS up to 20 regions (a hard limit of the operating system). If you exceed the limit, `addGeofences(...)` rejects with the `GEOFENCE_LIMIT_EXCEEDED` error code. If your app needs more regions, register only the geofences closest to the user and update them as the user moves.

### What radius should I use for a geofence?

Apple recommends a radius of at least 200 meters, as smaller radii may not trigger transitions reliably. See the [Apple documentation](https://developer.apple.com/documentation/corelocation/monitoring-the-user-s-proximity-to-geographic-regions) for details. On Android, a radius of at least 100 meters is recommended. There is no fixed maximum radius on Android, while iOS clamps the radius to `maximumRegionMonitoringDistance`. For the other reasons a geofence can stay silent on iOS, from the threshold rule to the permission level, see [Why Are Your Geofences Not Triggering on iOS?](https://capawesome.io/blog/why-are-your-geofences-not-triggering-on-ios/).

### Why does `addGeofences(...)` reject with a permission error?

Geofencing requires the **Always** location authorization on iOS and the **background location** permission on Android. If only the "while in use" (foreground) permission is granted, `addGeofences(...)` rejects with the `PERMISSION_DENIED` error code. See [Check and request permissions](#check-and-request-permissions) for the required two-step request flow.

### What happens to transitions that occur while my app is in the background or terminated?

If the queue is enabled, they are appended to it. It holds `1000` transitions by default and drops the **oldest** ones when it is full. Read them with `getQueuedTransitions(...)` when your app becomes active again — the `geofenceTransition` event only fires while your app is running and does not replay them. If a geofence defines a `notification`, it is displayed natively regardless of the app state. If your server needs to know about transitions right away instead of on the next launch, configure [HTTP Upload](#http-upload), which uploads them natively at the moment they are detected. On Android, geofences are automatically re-registered after a device reboot or an app update, while on iOS the monitored regions are persisted by the operating system.

### Why don't I receive dwell transitions on iOS?

Dwell transitions are only supported on Android. On iOS, the `androidNotifyOnDwell` and `androidLoiteringDelay` options are ignored, and only enter and exit transitions are reported.

### Why are `latitude` and `longitude` `null` on iOS?

Core Location does not provide the triggering location for a region transition. If you need the geofence's coordinates, look them up by its `geofenceId` (you already know them because you added the geofence).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/): Continuously track the device's location in the background.
- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/): Convert between coordinates and human-readable addresses.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geofences/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geofences/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geofences/LICENSE).

# Capacitor Google Play Services Plugin

Unofficial Capacitor plugin to check the availability of Google Play Services on Android and prompt the user to install or update it.[1](#fn:1)

## Features

- ✅ **Availability Check**: Check whether Google Play Services is installed, enabled and up to date.
- 🔍 **Status**: Find out why Google Play Services is not available, for example on Huawei or AOSP devices.
- 📲 **Resolution Dialog**: Prompt the user to install, enable or update Google Play Services with the system dialog.
- 🔢 **Version**: Read the version code of the installed Google Play Services APK.
- 🪶 **Lightweight**: Only depends on the `play-services-base` library, no other Google SDKs.
- 🔒 **Play Store safe**: Uses only official Google APIs.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Google Play Services plugin is typically used whenever an app depends on Google Play Services and wants to degrade gracefully on devices without it, for example:

- **Graceful degradation**: Hide or disable features that depend on Google Play Services, such as maps or push notifications, on devices without it.
- **Alternative services**: Fall back to alternative providers, such as Huawei Mobile Services, when Google Play Services is missing.
- **Update prompts**: Ask the user to update Google Play Services before using a feature that requires a recent version.
- **Diagnostics**: Include the Google Play Services status and version in bug reports and analytics.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-google-play-services` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-google-play-services
npx cap sync
```

### Android

#### 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:

- `$androidPlayServicesBaseVersion` version of `com.google.android.gms:play-services-base` (default: `18.10.1`)

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

### iOS

This plugin is not available on iOS.

### Web

This plugin is not available on the web.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check the availability of Google Play Services, detect devices without it, prompt the user to make it available and read the installed version.

### Check the availability

Check whether Google Play Services is installed, enabled and up to date before using a feature that depends on it:

```
import { GooglePlayServices } from '@capawesome/capacitor-google-play-services';

const isAvailable = async () => {
  const { available } = await GooglePlayServices.isAvailable();
  return available;
};
```

### Detect devices without Google Play Services

Some devices, such as Huawei devices with Huawei Mobile Services or devices with a custom Android build, ship without Google Play Services. Use the `getStatus()` method to find out why Google Play Services is not available and hide the features that depend on it:

```
import { GooglePlayServices, Status } from '@capawesome/capacitor-google-play-services';

const getStatus = async () => {
  const { status } = await GooglePlayServices.getStatus();
  if (status === Status.ServiceMissing) {
    console.log('This device has no Google Play Services.');
  } else if (status !== Status.Success) {
    console.log('Google Play Services is installed but not usable: ', status);
  }
};
```

### Make Google Play Services available

If Google Play Services is disabled, outdated or currently updating, prompt the user to fix it with the system dialog. The promise resolves once Google Play Services is available and is rejected with the `CANCELED` error code if the user dismisses the dialog:

```
import { ErrorCode, GooglePlayServices } from '@capawesome/capacitor-google-play-services';

const makeAvailable = async () => {
  try {
    await GooglePlayServices.makeAvailable();
    console.log('Google Play Services is now available.');
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user dismissed the dialog.');
    }
  }
};
```

### Get the version

Read the version code of the installed Google Play Services APK, for example to include it in bug reports:

```
import { GooglePlayServices } from '@capawesome/capacitor-google-play-services';

const getVersion = async () => {
  const { version } = await GooglePlayServices.getVersion();
  console.log('Google Play Services version: ', version);
};
```

## API

- [`getStatus()`](#getstatus)
- [`getVersion()`](#getversion)
- [`isAvailable()`](#isavailable)
- [`makeAvailable()`](#makeavailable)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getStatus()

```
getStatus() => Promise<GetStatusResult>
```

Get the status of Google Play Services on this device.

Use this method to find out why Google Play Services is not available, for example to distinguish devices without Google Play Services from devices with an outdated version.

Only available on Android.

**Returns:** `Promise<GetStatusResult>`

**Since:** 0.1.0

______________________________________________________________________

### getVersion()

```
getVersion() => Promise<GetVersionResult>
```

Get the version code of the Google Play Services APK installed on this device.

Only available on Android.

**Returns:** `Promise<GetVersionResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether Google Play Services is available on this device.

This resolves to `true` if Google Play Services is installed, enabled and up to date.

Only available on Android.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### makeAvailable()

```
makeAvailable() => Promise<void>
```

Make Google Play Services available on this device.

If Google Play Services is missing, disabled, outdated or currently updating, this shows the system dialog that prompts the user to install, enable or update it. The promise resolves once Google Play Services is available. If the user dismisses the dialog, the promise is rejected with the `CANCELED` error code. If Google Play Services can not be made available, for example on devices without the Google Play Store, the promise is rejected with the error message from Google Play Services.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetStatusResult

| Prop         | Type     | Description                                        | Since |
| ------------ | -------- | -------------------------------------------------- | ----- |
| **`status`** | `Status` | The status of Google Play Services on this device. | 0.1.0 |

#### GetVersionResult

| Prop          | Type     | Description                                                                                                                      | Since |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`version`** | `number` | The version code of the Google Play Services APK installed on this device. This is `0` if Google Play Services is not installed. | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                                      | Since |
| --------------- | --------- | ---------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not Google Play Services is available on this device. | 0.1.0 |

### Enums

#### Status

| Members                            | Value                               | Description                                                     | Since |
| ---------------------------------- | ----------------------------------- | --------------------------------------------------------------- | ----- |
| **`ServiceDisabled`**              | `'SERVICE_DISABLED'`                | Google Play Services is disabled on this device.                | 0.1.0 |
| **`ServiceInvalid`**               | `'SERVICE_INVALID'`                 | The installed version of Google Play Services is not authentic. | 0.1.0 |
| **`ServiceMissing`**               | `'SERVICE_MISSING'`                 | Google Play Services is not installed on this device.           | 0.1.0 |
| **`ServiceUpdating`**              | `'SERVICE_UPDATING'`                | Google Play Services is currently being updated on this device. | 0.1.0 |
| **`ServiceVersionUpdateRequired`** | `'SERVICE_VERSION_UPDATE_REQUIRED'` | The installed version of Google Play Services is out of date.   | 0.1.0 |
| **`Success`**                      | `'SUCCESS'`                         | Google Play Services is available.                              | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It focuses on one thing: telling your app whether Google Play Services can be used on the current device and, if not, why. It wraps the official `GoogleApiAvailability` API in a small, fully typed plugin that only depends on the `play-services-base` library, so you can degrade gracefully on devices without Google Play Services without pulling in Firebase, Maps or any other Google SDK. Actively maintained against the latest Capacitor version, it pairs naturally with the App Integrity, App Update and Google Sign-In plugins.

### Does this plugin work on iOS or Web?

No, this plugin only provides an Android implementation. Google Play Services does not exist on other platforms, so all methods are rejected with the `UNIMPLEMENTED` error code on iOS and Web. Check the platform with `Capacitor.getPlatform()` before calling the plugin in a cross-platform app.

### Does this plugin crash on devices without Google Play Services?

No. The availability check is part of the `play-services-base` library that is bundled with your app. It only asks the package manager whether Google Play Services is installed and signed by Google, so it works on any Android device, including devices without Google Play Services.

### How do I detect devices without Google Play Services, such as Huawei devices?

Call the `getStatus()` method. It resolves to `SERVICE_MISSING` on devices where Google Play Services is not installed at all, which is the case for Huawei devices with Huawei Mobile Services, Amazon Fire devices and custom Android builds. See [Detect devices without Google Play Services](#detect-devices-without-google-play-services).

### Why does `makeAvailable()` not work on my device?

The system dialog can only enable or update Google Play Services if it is already installed, or install it via the Google Play Store. On devices without the Google Play Store, such as Huawei devices with Huawei Mobile Services, there is no way to install Google Play Services and the promise is rejected. Check the status with the `getStatus()` method first and only call `makeAvailable()` if the status is `SERVICE_DISABLED`, `SERVICE_VERSION_UPDATE_REQUIRED` or `SERVICE_UPDATING`.

### Can I check the availability of a specific Google API, such as Maps or Location?

No, the plugin only checks the availability of Google Play Services as a whole. Individual Google APIs are covered by dedicated plugins.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API and App Attest.
- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Check for app updates and start in-app updates.
- [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/): Sign in with Google on Android, iOS and Web.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-play-services/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-play-services/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of its affiliates or subsidiaries. "Google Play" is a trademark of Google LLC. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Google Sign-In Plugin

Unofficial Capacitor plugin to sign-in with Google.[1](#fn:1)

## Features

The Capacitor Google Sign-In plugin is one of the most complete Google authentication solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🔐 **Authentication**: Sign in users with their Google account and receive an ID token (JWT).
- 🔑 **Authorization**: Optionally request OAuth scopes to get an access token and server auth code.
- 👤 **User Profile**: Retrieve the user's email, display name, profile picture, and more.
- 🛡️ **Nonce Support**: Prevent replay attacks with a custom nonce on Android and Web.
- 🪶 **Lightweight**: Just a single dependency and zero unnecessary bloat.
- 🚨 **Error Codes**: Provides detailed error codes for better error handling.
- 🤝 **Compatibility**: Compatible with the [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/) and [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Google Sign-In plugin is typically used wherever users should sign in with their existing Google account, for example:

- **Social login**: Let users sign in to your app with their Google account instead of creating a new password.
- **Backend authentication**: Send the ID token (JWT) to your backend to verify the user's identity.
- **Google API access**: Request OAuth scopes to receive an access token for accessing Google APIs on behalf of the user.
- **Server-side API access**: Exchange the server auth code on your backend for access and refresh tokens.
- **Profile pre-filling**: Use the user's email, display name, and profile picture to pre-fill their profile in your app.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Guides

- [How to Sign In with Google using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-google-using-capacitor/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-google-sign-in` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-google-sign-in
npx cap sync
```

On all platforms, your brand must be [verified](https://support.google.com/cloud/answer/13463073) for your app name to be shown on the Sign in with Google consent screen.

### Android

Create an **Android** OAuth client in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) in the same project as your web client:

- **Package name**: the application ID of your app (e.g. `com.example.app`), as defined in `android/app/build.gradle`.
- **SHA-1 certificate fingerprint**: the fingerprint of the certificate that signs the app.

**Attention**: The Android client ID is never passed to the plugin, because `initialize(...)` always receives the **web** client ID. The Android client must still exist and match the app, otherwise the sign-in flow fails.

Which SHA-1 fingerprint to use depends on how the app is signed:

- **Local debug builds**: the fingerprint of the debug keystore. Print it with `keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android`.
- **Builds distributed via Google Play**: the fingerprint of the **app signing key**, not the upload key. Find it in the Google Play Console under `Test and release` › `Setup` › `App signing`.

Add an OAuth client for every fingerprint you want to support. A missing fingerprint is the most common cause of a failing sign-in flow.

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxCredentialsVersion` version of `androidx.credentials:credentials` (default: `1.5.0`)
- `$googleIdVersion` version of `com.google.android.libraries.identity.googleid:googleid` (default: `1.1.1`)
- `$playServicesAuthVersion` version of `com.google.android.gms:play-services-auth` (default: `21.5.0`)

### iOS

Add the `GIDClientID` key to the `ios/App/App/Info.plist` file with your iOS client ID from the Google Cloud Console:

```
<key>GIDClientID</key>
<string>YOUR_IOS_CLIENT_ID</string>
```

You also need to add the URL scheme for your iOS client ID to the `ios/App/App/Info.plist` file:

```
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.YOUR_IOS_CLIENT_ID</string>
    </array>
  </dict>
</array>
```

Replace `YOUR_IOS_CLIENT_ID` with the reversed client ID from the Google Cloud Console (e.g. `com.googleusercontent.apps.123456789-abc`).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize the plugin, sign in and sign out a user, and complete the sign-in flow on the Web.

### Initialize the plugin

Call `initialize(...)` once before all other methods. The `clientId` must be a **web client ID** from the Google Cloud Console on all platforms, even on Android and iOS. Optionally provide `scopes` to also request authorization, which enables the access token and server auth code in the sign-in result:

```
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const initialize = async () => {
  await GoogleSignIn.initialize({
    clientId: '123456789-abc.apps.googleusercontent.com',
    scopes: ['https://www.googleapis.com/auth/userinfo.profile'],
  });
};
```

### Sign in a user

Start the Google Sign-In flow and retrieve the ID token (JWT) and the user's profile. Note that on Web, this redirects to the Google OAuth authorization page and the promise never resolves:

```
import { ErrorCode, GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const signIn = async () => {
  try {
    const result = await GoogleSignIn.signIn();
    console.log(result.idToken);
    console.log(result.userId);
    console.log(result.email);
    console.log(result.displayName);
    console.log(result.accessToken);
    console.log(result.serverAuthCode);
  } catch (error) {
    if (error.code === ErrorCode.SignInCanceled) {
      console.log('The user canceled the sign-in flow.');
    } else if (error.code === ErrorCode.NoCredentialAvailable) {
      console.log('No Google account is available on this device.');
    } else if (error.code === ErrorCode.ProviderConfigurationError) {
      console.log('Google Play services is not available or not up to date.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};
```

### Complete the sign-in flow on the Web

On Web, the app is redirected back to the `redirectUrl` after the user signs in. Call `handleRedirectCallback()` there to exchange the authorization code for tokens and complete the sign-in flow. Only available on Web:

```
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';
import { Capacitor } from '@capacitor/core';

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== 'web') {
    return;
  }
  const result = await GoogleSignIn.handleRedirectCallback();
  console.log(result.idToken);
  console.log(result.userId);
  console.log(result.email);
  console.log(result.displayName);
  console.log(result.accessToken);
  console.log(result.serverAuthCode);
};
```

### Sign out a user

Sign out the current user:

```
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const signOut = async () => {
  await GoogleSignIn.signOut();
};
```

## API

- [`handleRedirectCallback()`](#handleredirectcallback)
- [`initialize(...)`](#initialize)
- [`signIn(...)`](#signin)
- [`signOut()`](#signout)
- [Interfaces](#interfaces)

### handleRedirectCallback()

```
handleRedirectCallback() => Promise<SignInResult>
```

Handle the redirect callback from the OAuth provider.

This method must be called when the app is redirected back from the OAuth provider. It exchanges the authorization code for tokens and returns the sign-in result.

Only available on Web.

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the Google Sign-In plugin.

This method must be called once before all other methods.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### signIn(...)

```
signIn(options?: SignInOptions | undefined) => Promise<SignInResult>
```

Start the Google Sign-In flow.

On Web, this redirects to the Google OAuth authorization page. The promise will never resolve on Web. After the user signs in, the app will be redirected back to the `redirectUrl`. Use `handleRedirectCallback()` to complete the sign-in flow.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `SignInOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signOut()

```
signOut() => Promise<void>
```

Sign out the current user.

On Android, this clears the credential state. On iOS, this signs out from the Google Sign-In SDK. On Web, this is a no-op.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### SignInResult

| Prop                 | Type     | Description                                                                                     | Since                                                                                                                                                                       |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`idToken`**        | `string` | The ID token (JWT) returned by Google. This token can be sent to your backend for verification. | 0.1.0                                                                                                                                                                       |
| **`userId`**         | `string` | The unique identifier of the user's Google Account.                                             | 0.1.0                                                                                                                                                                       |
| **`email`**          | \`string | null\`                                                                                          | The user's email address.                                                                                                                                                   |
| **`displayName`**    | \`string | null\`                                                                                          | The user's display name (full name).                                                                                                                                        |
| **`givenName`**      | \`string | null\`                                                                                          | The user's given name (first name).                                                                                                                                         |
| **`familyName`**     | \`string | null\`                                                                                          | The user's family name (last name).                                                                                                                                         |
| **`imageUrl`**       | \`string | null\`                                                                                          | The URL of the user's profile picture.                                                                                                                                      |
| **`accessToken`**    | \`string | null\`                                                                                          | The access token for accessing Google APIs. Only available when `scopes` are configured in `initialize()`.                                                                  |
| **`serverAuthCode`** | \`string | null\`                                                                                          | The server auth code that can be exchanged on your backend for access and refresh tokens. Only available on Android and iOS when `scopes` are configured in `initialize()`. |

#### InitializeOptions

| Prop              | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                          | Since |
| ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`clientId`**    | `string`   | The web client ID from Google Cloud Console. On Android, this is passed as the server client ID to the Credential Manager API and the AuthorizationClient API. On iOS, this is used as the server client ID for the Google Sign-In SDK. On Web, this is used to initialize the Google Sign-In JavaScript API. **Attention**: This must be a web client ID on all platforms, even on Android and iOS. | 0.1.0 |
| **`redirectUrl`** | `string`   | The URL to redirect to after the OAuth flow. Only available on Web.                                                                                                                                                                                                                                                                                                                                  | 0.1.0 |
| **`scopes`**      | `string[]` | The OAuth scopes to request. If provided, the plugin will request authorization in addition to authentication. This enables `accessToken` and `serverAuthCode` in the sign-in result.                                                                                                                                                                                                                | 0.1.0 |

#### SignInOptions

| Prop        | Type     | Description                                                           | Since |
| ----------- | -------- | --------------------------------------------------------------------- | ----- |
| **`nonce`** | `string` | A nonce to prevent replay attacks. Only available on Android and Web. | 0.1.0 |

## Security

This plugin handles the OAuth flow and returns tokens to your app. To keep your integration secure, be aware of the following:

- **Server-side token verification is required.** The `idToken` (JWT) is **not** verified client-side. Your backend **must** verify the JWT signature using [Google's public keys](https://www.googleapis.com/oauth2/v3/certs) before trusting any claims (e.g. `userId`, `email`). Never use client-side token data for authorization decisions without server-side verification.
- **Exchange `serverAuthCode` on your backend.** If you use scopes, send the `serverAuthCode` to your backend and exchange it there for access and refresh tokens. Never exchange it client-side, as this would expose your client secret.

## FAQ

### What's the difference between this plugin and other Google Sign-In plugins?

This plugin is purpose-built for Google Sign-In and focuses on providing a clean and modern API with the latest platform features. Here are some of the key differences:

- **Cross-platform**: Supports Android, iOS, and Web.
- **Lightweight**: No unnecessary dependencies. Just Google Sign-In, nothing else.
- **No deprecated APIs**: Uses the latest platform APIs (Credential Manager on Android, Google Sign-In SDK on iOS).
- **Authentication + Authorization**: Supports both authentication (ID tokens) and authorization (access tokens, server auth codes) in a single flow.
- **Error codes**: Provides typed error codes for proper error handling.
- **Redirect flow on Web**: Uses a redirect-based OAuth flow instead of popups, resulting in a more reliable and user-friendly experience.

### Why do I need a web client ID on Android and iOS?

The `clientId` option must be a web client ID from the Google Cloud Console on all platforms. On Android, it is passed as the server client ID to the Credential Manager API and the AuthorizationClient API. On iOS, it is used as the server client ID for the Google Sign-In SDK. On iOS, you additionally configure your iOS client ID via the `GIDClientID` key in the `Info.plist` file, see the [Installation](#installation) section.

### Why does the `signIn` promise never resolve on the Web?

On Web, the plugin uses a redirect-based OAuth flow. The `signIn(...)` method redirects to the Google OAuth authorization page, so the promise never resolves. After the user signs in, the app is redirected back to the `redirectUrl` and you must call `handleRedirectCallback()` to complete the sign-in flow, see the [usage example](#complete-the-sign-in-flow-on-the-web) above.

### How do I get an access token for Google APIs?

Configure the `scopes` option in the `initialize(...)` method. The plugin then requests authorization in addition to authentication, which enables the `accessToken` and `serverAuthCode` properties in the sign-in result. If you need access and refresh tokens on your backend, exchange the `serverAuthCode` there, never client-side, as described in the [Security](#security) section.

### Why does the sign-in flow fail on Android right after picking an account?

If the account picker opens but the flow fails as soon as an account is picked, the app is most likely missing a matching Android OAuth client. Look for one of the following entries in the logcat output:

```
Auth.Api.Credentials: colz: [8] Unknown error [status=UNREGISTERED_ON_API_CONSOLE].
Auth.Api.Credentials: colz: [16] Account reauth failed.
```

Google Play services reports this as a cancellation, so the plugin rejects the call with the `SIGN_IN_CANCELED` error code and `Account reauth failed` as the error message. Make sure that an Android OAuth client exists for the package name and the SHA-1 fingerprint of the certificate that signs the app, as described in the [Installation](#android) section. Builds distributed via Google Play must use the fingerprint of the app signing key, not the upload key.

## Related Plugins

- [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/): Sign in users with their Apple account.
- [Facebook Sign-In](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/): Sign in users with their Facebook account.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with any OAuth 2.0 and OpenID Connect provider.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-sign-in/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-sign-in/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Grafana Faro Plugin

Unofficial Capacitor plugin for [Grafana Faro](https://grafana.com/oss/faro/).[1](#fn:1)

> ⚠️ **Experimental:** This plugin is in early development. APIs may change between minor versions. Feedback and bug reports are very welcome — please [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues).

## Features

The Capacitor Grafana Faro plugin is one of the most complete frontend observability solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 📝 **Logs**: Capture log messages with severity levels and structured context.
- 📡 **Events**: Track custom events with attributes and a platform domain.
- 💥 **Errors**: Capture errors with optional stack frames (compatible with [`stacktrace.js`](https://www.stacktracejs.com/)).
- 📊 **Measurements**: Record numeric metrics for performance and business KPIs.
- 👤 **User, Session and View Metadata**: Attach user, session and view information to every signal.
- 🛡️ **Native Crash Reporting**: Capture native crashes via [PLCrashReporter](https://github.com/microsoft/plcrashreporter) on iOS and [`ApplicationExitInfo`](https://developer.android.com/reference/android/app/ApplicationExitInfo) on Android.
- 🐌 **ANR Detection**: Detect Application Not Responding events on the Android main thread.
- 🌐 **Web Auto-Instrumentation**: Automatically capture uncaught errors, console output, Core Web Vitals, route changes and network performance on Web.
- ⏯️ **Pause and Resume**: Pause and resume telemetry on demand.
- 🎯 **Session Sampling**: Sample sessions with a configurable rate to control data volume.
- 🤝 **Compatibility**: Works alongside the [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/) and [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/) plugins.

## Use Cases

The Grafana Faro plugin is typically used to monitor Capacitor apps in production, for example:

- **Crash and error monitoring**: Capture JavaScript errors as well as native crashes on Android and iOS and analyze them in Grafana.
- **Performance monitoring**: Record Core Web Vitals and network performance on Web, or push custom measurements such as startup or sign-in durations.
- **Usage analytics**: Track custom events with attributes to understand how users move through your app.
- **Centralized logging**: Send log messages with severity levels and structured context to your Faro collector.
- **Stability monitoring on Android**: Detect Application Not Responding (ANR) events on the main thread.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-grafana-faro` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-grafana-faro @grafana/faro-web-sdk
npx cap sync
```

### iOS

#### Minimum Deployment Target

This plugin depends on [PLCrashReporter](https://github.com/microsoft/plcrashreporter) for native crash reporting. Make sure that your iOS deployment target is set to at least `15.0` in your Xcode project settings (usually in `ios/App/App.xcodeproj`):

```
-IPHONEOS_DEPLOYMENT_TARGET = 14.0
+IPHONEOS_DEPLOYMENT_TARGET = 15.0
```

If you are using **CocoaPods**, make sure that your iOS deployment target is set to at least `15.0` in your `Podfile`:

```
platform :ios, '15.0'
```

#### Conflicts with other crash reporters

PLCrashReporter installs global crash handlers. Running this plugin alongside another crash reporter that also installs handlers (e.g. Firebase Crashlytics, Sentry) can lead to one or both reporters losing crash reports. Enable `instrumentations.nativeCrashReporting` only when no other crash reporter is active.

## Configuration

Build-time configuration for the Grafana Faro plugin.

When `url` and `appName` are both provided, the native plugin auto-initializes during app startup. This allows native crash and ANR handlers to be installed before any JavaScript code runs. Calling `GrafanaFaro.initialize(...)` from JavaScript afterwards is not required and will fail with an `already initialized` error.

Only applies to Android and iOS.

| Prop                   | Type                                                         | Description                                                                                                                | Since |
| ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`apiKey`**           | `string`                                                     | The API key sent as the `x-api-key` header.                                                                                | 0.1.0 |
| **`appEnvironment`**   | `string`                                                     | The environment of the application (e.g. `production`, `staging`).                                                         | 0.1.0 |
| **`appName`**          | `string`                                                     | The name of the application.                                                                                               | 0.1.0 |
| **`appNamespace`**     | `string`                                                     | The namespace of the application.                                                                                          | 0.1.0 |
| **`appVersion`**       | `string`                                                     | The version of the application.                                                                                            | 0.1.0 |
| **`instrumentations`** | `{ anrTracking?: boolean; nativeCrashReporting?: boolean; }` | Toggles for built-in automatic instrumentations. Only the toggles that apply at build time on Android and iOS are honored. | 0.1.0 |
| **`url`**              | `string`                                                     | The Faro collector endpoint URL.                                                                                           | 0.1.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "GrafanaFaro": {
      "apiKey": undefined,
      "appEnvironment": undefined,
      "appName": undefined,
      "appNamespace": undefined,
      "appVersion": undefined,
      "instrumentations": undefined,
      "url": 'https://faro-collector-prod.grafana.net/collect/<token>'
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-grafana-faro" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    GrafanaFaro: {
      apiKey: undefined,
      appEnvironment: undefined,
      appName: undefined,
      appNamespace: undefined,
      appVersion: undefined,
      instrumentations: undefined,
      url: 'https://faro-collector-prod.grafana.net/collect/<token>',
    },
  },
};

export default config;
```

## Usage

The following examples show how to initialize the Faro SDK, send log messages, track custom events, capture errors, record measurements, and attach user and view metadata.

### Initialize the Faro SDK

Call `initialize(...)` before any other method to connect the plugin to your Faro collector endpoint. Alternatively, provide the `url` and `appName` options in the [Configuration](#configuration) so that the native plugin auto-initializes during app startup:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const initialize = async () => {
  await GrafanaFaro.initialize({
    app: {
      environment: 'production',
      name: 'my-app',
      version: '1.0.0',
    },
    instrumentations: {
      anrTracking: true,
      console: true,
      errors: true,
      nativeCrashReporting: true,
      performance: true,
      view: true,
      webVitals: true,
    },
    url: 'https://faro-collector-prod-us-central-0.grafana.net/collect/REPLACE_ME',
  });
};
```

### Send log messages

Capture log messages with a severity level and an optional structured context:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const pushLog = async () => {
  await GrafanaFaro.pushLog({
    level: 'info',
    message: 'User pressed sign-in button',
  });
};
```

### Track custom events

Track user interactions or business events with custom attributes:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const pushEvent = async () => {
  await GrafanaFaro.pushEvent({
    attributes: { provider: 'google' },
    name: 'sign_in_started',
  });
};
```

### Capture errors

Push errors with an optional pre-parsed stack trace. Use a library like `stacktrace-js` to parse the stack into structured frames:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const pushError = async (error: Error) => {
  await GrafanaFaro.pushError({
    type: error.name,
    value: error.message,
  });
};

const pushErrorWithStacktrace = async (error: Error) => {
  // Use `stacktrace-js` (or any equivalent) to parse the stack into
  // structured frames.
  const StackTrace = await import('stacktrace-js');
  const stackFrames = await StackTrace.fromError(error);
  await GrafanaFaro.pushError({
    type: error.name,
    value: error.message,
    stackFrames: stackFrames.map(frame => ({
      columnNumber: frame.columnNumber,
      fileName: frame.fileName,
      functionName: frame.functionName,
      lineNumber: frame.lineNumber,
    })),
  });
};
```

### Record measurements

Record numeric metrics, for example performance timings or business KPIs:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const pushMeasurement = async () => {
  await GrafanaFaro.pushMeasurement({
    type: 'sign_in_duration',
    values: { duration_ms: 320 },
  });
};
```

### Attach user and view metadata

Attach user and view information to every signal:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

const setUser = async () => {
  await GrafanaFaro.setUser({
    email: 'jane@example.com',
    id: 'user-123',
    username: 'jane',
  });
};

const setView = async () => {
  await GrafanaFaro.setView({ name: 'SignInView' });
};
```

## API

- [`getSession()`](#getsession)
- [`getView()`](#getview)
- [`initialize(...)`](#initialize)
- [`pause()`](#pause)
- [`pushError(...)`](#pusherror)
- [`pushEvent(...)`](#pushevent)
- [`pushLog(...)`](#pushlog)
- [`pushMeasurement(...)`](#pushmeasurement)
- [`resetSession()`](#resetsession)
- [`resetUser()`](#resetuser)
- [`setSession(...)`](#setsession)
- [`setUser(...)`](#setuser)
- [`setView(...)`](#setview)
- [`unpause()`](#unpause)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getSession()

```
getSession() => Promise<GetSessionResult>
```

Get the current session.

**Returns:** `Promise<GetSessionResult>`

**Since:** 0.1.0

______________________________________________________________________

### getView()

```
getView() => Promise<GetViewResult>
```

Get the current view.

**Returns:** `Promise<GetViewResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the Faro SDK.

**Attention**: This method must be called before any other method.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pause()

```
pause() => Promise<void>
```

Pause sending telemetry. New signals are still buffered locally.

**Since:** 0.1.0

______________________________________________________________________

### pushError(...)

```
pushError(options: PushErrorOptions) => Promise<void>
```

Push an error/exception.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PushErrorOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pushEvent(...)

```
pushEvent(options: PushEventOptions) => Promise<void>
```

Push a custom event.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PushEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pushLog(...)

```
pushLog(options: PushLogOptions) => Promise<void>
```

Push a log message.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `PushLogOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pushMeasurement(...)

```
pushMeasurement(options: PushMeasurementOptions) => Promise<void>
```

Push a measurement (numeric metric).

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `PushMeasurementOptions` |

**Since:** 0.1.0

______________________________________________________________________

### resetSession()

```
resetSession() => Promise<void>
```

Clear the current session and start a new one.

**Since:** 0.1.0

______________________________________________________________________

### resetUser()

```
resetUser() => Promise<void>
```

Clear the current user.

**Since:** 0.1.0

______________________________________________________________________

### setSession(...)

```
setSession(options: SetSessionOptions) => Promise<void>
```

Set the current session.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetSessionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUser(...)

```
setUser(options: SetUserOptions) => Promise<void>
```

Set the current user.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `UserMetadata` |

**Since:** 0.1.0

______________________________________________________________________

### setView(...)

```
setView(options: SetViewOptions) => Promise<void>
```

Set the current view (e.g. screen / route name).

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `ViewMetadata` |

**Since:** 0.1.0

______________________________________________________________________

### unpause()

```
unpause() => Promise<void>
```

Resume sending telemetry.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetSessionResult

| Prop             | Type                         | Description                     | Since |
| ---------------- | ---------------------------- | ------------------------------- | ----- |
| **`attributes`** | `{ [key: string]: string; }` | The current session attributes. | 0.1.0 |
| **`id`**         | `string`                     | The current session ID.         | 0.1.0 |

#### GetViewResult

| Prop       | Type     | Description            | Since |
| ---------- | -------- | ---------------------- | ----- |
| **`name`** | `string` | The current view name. | 0.1.0 |

#### InitializeOptions

| Prop                      | Type                         | Description                                                         | Default | Since |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------- | ------- | ----- |
| **`apiKey`**              | `string`                     | API key sent as the `x-api-key` header to the collector.            |         | 0.1.0 |
| **`app`**                 | `AppMetadata`                | Application metadata attached to every signal.                      |         | 0.1.0 |
| **`ignoreErrors`**        | `string[]`                   | Error message patterns to ignore.                                   |         | 0.1.0 |
| **`ignoreUrls`**          | `string[]`                   | URL patterns to ignore when instrumenting network calls.            |         | 0.1.0 |
| **`instrumentations`**    | `InstrumentationsOptions`    | Toggles for built-in automatic instrumentations.                    |         | 0.1.0 |
| **`paused`**              | `boolean`                    | Start in a paused state. Telemetry must be resumed via `unpause()`. | `false` | 0.1.0 |
| **`sessionAttributes`**   | `{ [key: string]: string; }` | Initial session attributes.                                         |         | 0.1.0 |
| **`sessionSamplingRate`** | `number`                     | Session sampling rate in `[0, 1]`. `1` = all sessions, `0` = none.  | `1`     | 0.1.0 |
| **`url`**                 | `string`                     | The Faro collector endpoint URL.                                    |         | 0.1.0 |
| **`user`**                | `UserMetadata`               | Initial user metadata.                                              |         | 0.1.0 |
| **`view`**                | `ViewMetadata`               | Initial view metadata.                                              |         | 0.1.0 |

#### AppMetadata

| Prop              | Type     | Description                                                        | Since |
| ----------------- | -------- | ------------------------------------------------------------------ | ----- |
| **`environment`** | `string` | The environment of the application (e.g. `production`, `staging`). | 0.1.0 |
| **`name`**        | `string` | The name of the application.                                       | 0.1.0 |
| **`namespace`**   | `string` | The namespace of the application.                                  | 0.1.0 |
| **`version`**     | `string` | The version of the application.                                    | 0.1.0 |

#### InstrumentationsOptions

Toggles for built-in automatic instrumentations.

Note: some toggles only apply on specific platforms. The plugin silently ignores toggles that do not apply on the current platform.

| Prop                       | Type      | Description                                                                                | Default | Since |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------ | ------- | ----- |
| **`anrTracking`**          | `boolean` | Detect Application Not Responding events on the main thread. Only available for Android.   | `false` | 0.1.0 |
| **`console`**              | `boolean` | Capture `console.warn` and `console.error` calls. Only available for Web.                  | `true`  | 0.1.0 |
| **`errors`**               | `boolean` | Capture uncaught errors and unhandled promise rejections. Only available for Web.          | `true`  | 0.1.0 |
| **`nativeCrashReporting`** | `boolean` | Capture native crashes (reported on the next session). Only available for Android and iOS. | `false` | 0.1.0 |
| **`performance`**          | `boolean` | Capture `fetch` and `XHR` performance entries. Only available for Web.                     | `true`  | 0.1.0 |
| **`view`**                 | `boolean` | Capture History API navigation as view changes. Only available for Web.                    | `true`  | 0.1.0 |
| **`webVitals`**            | `boolean` | Capture Core Web Vitals (LCP, FID, CLS, INP, TTFB). Only available for Web.                | `true`  | 0.1.0 |

#### UserMetadata

| Prop             | Type                         | Description                                   | Since |
| ---------------- | ---------------------------- | --------------------------------------------- | ----- |
| **`attributes`** | `{ [key: string]: string; }` | Additional key-value attributes for the user. | 0.1.0 |
| **`email`**      | `string`                     | The user's email address.                     | 0.1.0 |
| **`fullName`**   | `string`                     | The user's full name.                         | 0.1.0 |
| **`id`**         | `string`                     | The user's ID.                                | 0.1.0 |
| **`username`**   | `string`                     | The user's username.                          | 0.1.0 |

#### ViewMetadata

| Prop       | Type     | Description           | Since |
| ---------- | -------- | --------------------- | ----- |
| **`name`** | `string` | The name of the view. | 0.1.0 |

#### PushErrorOptions

| Prop              | Type                         | Description                                           | Default | Since |
| ----------------- | ---------------------------- | ----------------------------------------------------- | ------- | ----- |
| **`context`**     | `{ [key: string]: string; }` | Additional context attached to the error.             |         | 0.1.0 |
| **`fatal`**       | `boolean`                    | Mark the error as fatal (e.g. caused a crash).        | `false` | 0.1.0 |
| **`stackFrames`** | `StackFrame[]`               | Pre-parsed stack frames generated by `stacktrace.js`. |         | 0.1.0 |
| **`type`**        | `string`                     | The error type (e.g. `'TypeError'`).                  |         | 0.1.0 |
| **`value`**       | `string`                     | The error message.                                    |         | 0.1.0 |

#### StackFrame

Subset of the stacktrace generated by `stacktrace.js`.

| Prop               | Type     | Since |
| ------------------ | -------- | ----- |
| **`columnNumber`** | `number` | 0.1.0 |
| **`fileName`**     | `string` | 0.1.0 |
| **`functionName`** | `string` | 0.1.0 |
| **`lineNumber`**   | `number` | 0.1.0 |

#### PushEventOptions

| Prop             | Type                         | Description                                                                                      | Since |
| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ | ----- |
| **`attributes`** | `{ [key: string]: string; }` | Key-value attributes attached to the event.                                                      | 0.1.0 |
| **`domain`**     | `string`                     | Logical grouping for the event. Defaults to the platform domain (`'web'`, `'android'`, `'ios'`). | 0.1.0 |
| **`name`**       | `string`                     | The name of the event.                                                                           | 0.1.0 |

#### PushLogOptions

| Prop          | Type                         | Description                             | Default  | Since |
| ------------- | ---------------------------- | --------------------------------------- | -------- | ----- |
| **`context`** | `{ [key: string]: string; }` | Additional context attached to the log. |          | 0.1.0 |
| **`level`**   | `LogLevel`                   | The log level.                          | `'info'` | 0.1.0 |
| **`message`** | `string`                     | The log message.                        |          | 0.1.0 |

#### PushMeasurementOptions

| Prop          | Type                         | Description                                     | Since |
| ------------- | ---------------------------- | ----------------------------------------------- | ----- |
| **`context`** | `{ [key: string]: string; }` | Additional context attached to the measurement. | 0.1.0 |
| **`type`**    | `string`                     | The measurement type (e.g. `'custom_latency'`). | 0.1.0 |
| **`values`**  | `{ [key: string]: number; }` | Key-value numeric measurements.                 | 0.1.0 |

#### SetSessionOptions

| Prop             | Type                         | Description                                               | Since |
| ---------------- | ---------------------------- | --------------------------------------------------------- | ----- |
| **`attributes`** | `{ [key: string]: string; }` | The session attributes.                                   | 0.1.0 |
| **`id`**         | `string`                     | Optional session ID. A UUID v4 is generated when omitted. | 0.1.0 |

### Type Aliases

#### LogLevel

`'debug' | 'error' | 'info' | 'log' | 'trace' | 'warn'`

#### SetUserOptions

`UserMetadata`

#### SetViewOptions

`ViewMetadata`

## FAQ

### Is this an official Grafana Labs plugin?

No, this is an unofficial plugin maintained by Capawesome. The project is not affiliated with, endorsed by, sponsored by, or approved by Grafana Labs or any of their affiliates or subsidiaries. It integrates [Grafana Faro](https://grafana.com/oss/faro/) into Capacitor apps.

### Can I use this plugin together with Firebase Crashlytics or Sentry?

Only with care. The plugin uses PLCrashReporter for native crash reporting on iOS, which installs global crash handlers. Running it alongside another crash reporter that also installs handlers (for example Firebase Crashlytics or Sentry) can lead to one or both reporters losing crash reports. Enable the `instrumentations.nativeCrashReporting` toggle only when no other crash reporter is active.

### Why does the plugin fail with an `already initialized` error?

If you provide the `url` and `appName` options in the plugin [configuration](#configuration), the native plugin auto-initializes during app startup so that native crash and ANR handlers are installed before any JavaScript code runs. In that case, calling `GrafanaFaro.initialize(...)` from JavaScript is not required and will fail with an `already initialized` error.

### How does native crash reporting work?

Native crashes are captured via [PLCrashReporter](https://github.com/microsoft/plcrashreporter) on iOS and [`ApplicationExitInfo`](https://developer.android.com/reference/android/app/ApplicationExitInfo) on Android and are reported on the next session. The `instrumentations.nativeCrashReporting` toggle is disabled by default, and on iOS your deployment target must be set to at least `15.0` (see [Installation](#installation)).

### How can I reduce the amount of telemetry that is sent?

You can set the `sessionSamplingRate` option to a value between `0` and `1` to only report a subset of sessions. You can also pause and resume telemetry on demand using the `pause()` and `unpause()` methods, or start in a paused state with the `paused` option.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Unofficial Capacitor plugin for Firebase Analytics.
- [Firebase Crashlytics](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/): Unofficial Capacitor plugin for Firebase Crashlytics crash reporting.
- [Firebase Performance Monitoring](https://capawesome.io/docs/sdks/capacitor/firebase/performance-monitoring/): Unofficial Capacitor plugin for Firebase Performance Monitoring.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for the PostHog product analytics platform.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/grafana-faro/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/grafana-faro/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Grafana Labs or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Gyroscope Plugin

Capacitor plugin to read the device's gyroscope sensor.

## Features

The Capacitor Gyroscope plugin is one of the most complete motion sensing solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- ⚡ **Real-time measurements**: Continuous gyroscope data with event listeners.
- 📊 **Rotation rate**: Accurate x, y, and z-axis rotation rate in rad/s.
- 🔒 **Permission handling**: Built-in permission management for sensor access.
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/) and [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Gyroscope plugin is typically used whenever an app needs to react to the rotation of the device, for example:

- **Motion-controlled games**: Use the real-time rotation rate to steer a character or vehicle by tilting the device.
- **Immersive experiences**: Rotate 360° views or augmented reality scenes based on the device's rotation.
- **Gesture detection**: Detect rotation gestures such as twisting the device to trigger actions in your app.
- **Motion analysis**: Record the rotation rate around the x, y, and z axes to analyze movement patterns.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How rotation data powers tilt-to-steer game mechanics and AR features together with the Accelerometer.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-gyroscope` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-gyroscope
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSMotionUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the device's motion data:

```
<key>NSMotionUsageDescription</key>
<string>The app needs to access the motion activity.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check if the gyroscope is available, get a single measurement, receive continuous measurement updates, check and request permissions, and remove all listeners.

### Check if the gyroscope is available

Check whether the device has a gyroscope sensor before using the other methods:

```
import { Gyroscope } from '@capawesome/capacitor-gyroscope';

const isAvailable = async () => {
  const result = await Gyroscope.isAvailable();
  return result.available;
};
```

### Get a single measurement

Get the most recent measurement from the gyroscope sensor. The rotation rate around the x, y, and z axes is reported in radians per second (rad/s):

```
import { Gyroscope } from '@capawesome/capacitor-gyroscope';

const getMeasurement = async () => {
  const measurement = await Gyroscope.getMeasurement();
  console.log('X: ', measurement.x);
  console.log('Y: ', measurement.y);
  console.log('Z: ', measurement.z);
};
```

### Receive continuous measurement updates

Add a listener for the `measurement` event and start the measurement updates to receive the rotation rate in real time. The `measurement` event is only available on Android and iOS:

```
import { Gyroscope } from '@capawesome/capacitor-gyroscope';

const startMeasurementUpdates = async () => {
  await Gyroscope.addListener('measurement', measurement => {
    console.log('X: ', measurement.x);
    console.log('Y: ', measurement.y);
    console.log('Z: ', measurement.z);
  });
  await Gyroscope.startMeasurementUpdates();
};

const stopMeasurementUpdates = async () => {
  await Gyroscope.stopMeasurementUpdates();
};
```

### Check and request permissions

Check and request the permission to access the gyroscope sensor:

```
import { Gyroscope } from '@capawesome/capacitor-gyroscope';

const checkPermissions = async () => {
  const result = await Gyroscope.checkPermissions();
  return result;
};

const requestPermissions = async () => {
  const result = await Gyroscope.requestPermissions();
  return result;
};
```

### Remove all listeners

Remove all listeners when you no longer need them:

```
import { Gyroscope } from '@capawesome/capacitor-gyroscope';

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

## API

- [`checkPermissions()`](#checkpermissions)
- [`getMeasurement()`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`requestPermissions()`](#requestpermissions)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check if the app has permission to access the gyroscope sensor.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### getMeasurement()

```
getMeasurement() => Promise<GetMeasurementResult>
```

Get the latest measurement.

This method returns the most recent measurement from the gyroscope sensor.

**Returns:** `Promise<Measurement>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the gyroscope sensor is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to access the gyroscope sensor.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Start emitting `measurement` events.

**Since:** 0.1.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stop emitting `measurement` events.

**Since:** 0.1.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new measurement is available.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop            | Type                       | Description                                    | Since |
| --------------- | -------------------------- | ---------------------------------------------- | ----- |
| **`gyroscope`** | `GyroscopePermissionState` | The permission status of the gyroscope sensor. | 0.1.0 |

#### Measurement

| Prop    | Type     | Description                                                        | Since |
| ------- | -------- | ------------------------------------------------------------------ | ----- |
| **`x`** | `number` | The rotation rate around the x-axis in radians per second (rad/s). | 0.1.0 |
| **`y`** | `number` | The rotation rate around the y-axis in radians per second (rad/s). | 0.1.0 |
| **`z`** | `number` | The rotation rate around the z-axis in radians per second (rad/s). | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                              | Since |
| --------------- | --------- | -------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether the gyroscope sensor is available on the device. | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GyroscopePermissionState

`PermissionState | 'limited'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### GetMeasurementResult

`Measurement`

#### MeasurementEvent

`Measurement`

## FAQ

### How is this plugin different from other similar plugins?

It delivers accurate x, y, and z-axis rotation rate in rad/s with both one-off readings via `getMeasurement()` and continuous real-time updates via the `measurement` event, plus built-in permission handling for sensor access on Android and iOS. The API is fully typed and actively maintained against the latest Capacitor and OS versions, and it pairs cleanly with our Accelerometer, Barometer, and Pedometer plugins so a single, consistent motion-sensing story is covered. If you only need an occasional reading, a simpler setup is perfectly fine; if you need continuous, low-level rotation data, this plugin is built for exactly that.

### Which platforms does the plugin support?

The plugin supports Android and iOS. The continuous `measurement` event is only emitted on Android and iOS, so there is no gyroscope support in the browser.

### What units are the measurements reported in?

Each measurement contains the rotation rate around the x, y, and z axes in radians per second (rad/s).

### What is the difference between `getMeasurement` and the `measurement` event?

The `getMeasurement()` method returns the most recent measurement from the gyroscope sensor once. If you need continuous real-time updates instead, add a listener for the `measurement` event and call `startMeasurementUpdates()`. Call `stopMeasurementUpdates()` when you no longer need updates.

### Do I need any permissions to read the gyroscope?

The plugin provides the `checkPermissions()` and `requestPermissions()` methods to manage access to the gyroscope sensor. On iOS, you also have to add the `NSMotionUsageDescription` key to your `Info.plist` file, which tells the user why your app needs access to the device's motion data (see [Installation](#installation)).

### How do I know if the device has a gyroscope sensor?

Call the `isAvailable()` method. It returns whether the gyroscope sensor is available on the device, so you can hide or disable motion features on devices without a gyroscope.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure measured in hectopascals (hPa).
- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device compass heading.
- [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/): Retrieve motion data such as the number of steps and the distance traveled.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/gyroscope/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/gyroscope/LICENSE).

# Capacitor Haptics Plugin

Capacitor plugin to provide haptic feedback such as impacts, notifications, vibrations and custom haptic patterns.

## Features

- 💥 **Impact**: Trigger impact haptic feedback with five different styles, including the modern `Rigid` and `Soft` styles.
- 🔔 **Notification**: Trigger notification haptic feedback for success, warning and error events.
- 🎯 **Selection**: Trigger selection haptic feedback for picker-style interactions.
- 🎼 **Custom patterns**: Play custom haptic patterns with per-event intensity and sharpness (Core Haptics on iOS, vibration effects on Android).
- 🤖 **Android haptics**: Perform semantic Android haptic feedback effects that respect the user's haptic feedback settings.
- 📳 **Vibrate**: Vibrate the device with a custom duration.
- 🔎 **Availability check**: Check if haptic feedback is available on the device.
- 🌐 **Web support**: Best-effort support for the Web using the Vibration API.
- 🤝 **Compatibility**: Works alongside the [Shake](https://capawesome.io/docs/sdks/capacitor/shake/), [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/) and [Volume](https://capawesome.io/docs/sdks/capacitor/volume/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Haptics plugin is typically used to make an app feel more responsive and tactile, for example:

- **Button and gesture feedback**: Trigger impact feedback when user interface elements collide or a drag operation snaps into place.
- **Success and error feedback**: Use notification haptics to communicate that a task has succeeded, failed, or produced a warning.
- **Pickers and selection controls**: Give subtle selection feedback while the user scrolls through a picker.
- **Games and rich interactions**: Play custom haptic patterns with per-event intensity and sharpness for immersive experiences.
- **Alerts**: Vibrate the device with a custom duration to get the user's attention.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-haptics` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-haptics
npx cap sync
```

### Android

This plugin already declares the `android.permission.VIBRATE` permission in its manifest, so no additional configuration is required.

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check if haptic feedback is available, trigger impact and notification feedback, give selection feedback, play a custom haptic pattern, perform an Android haptic effect, and vibrate the device.

### Check if haptic feedback is available

Check whether the device supports haptic feedback before using the other methods:

```
import { Haptics } from '@capawesome/capacitor-haptics';

const isAvailable = async () => {
  const { available } = await Haptics.isAvailable();
  return available;
};
```

### Trigger impact feedback

Simulate a physical impact, for example when user interface elements collide or a drag operation snaps into place. Five different styles are available, including the modern `Rigid` and `Soft` styles:

```
import { Haptics, ImpactStyle } from '@capawesome/capacitor-haptics';

const impact = async () => {
  await Haptics.impact({ style: ImpactStyle.Medium });
};
```

### Trigger notification feedback

Communicate that a task or action has succeeded, failed, or produced a warning:

```
import { Haptics, NotificationType } from '@capawesome/capacitor-haptics';

const notification = async () => {
  await Haptics.notification({ type: NotificationType.Success });
};
```

### Give selection feedback

Give subtle feedback during picker-style interactions. Call `selectionStart()` when the interaction begins, `selectionChanged()` whenever the selection changes, and `selectionEnd()` when the interaction finishes:

```
import { Haptics } from '@capawesome/capacitor-haptics';

const selection = async () => {
  await Haptics.selectionStart();
  await Haptics.selectionChanged();
  await Haptics.selectionEnd();
};
```

### Play a custom haptic pattern

Play a custom pattern composed of individual haptic events with per-event intensity and sharpness. On iOS, the pattern is played using Core Haptics; on Android, it is approximated using vibration effects:

```
import { Haptics } from '@capawesome/capacitor-haptics';

const playPattern = async () => {
  await Haptics.playPattern({
    events: [
      { time: 0, intensity: 1, sharpness: 0.8 },
      { time: 0.2, intensity: 0.6, sharpness: 0.4 },
      { time: 0.4, intensity: 0.8, duration: 0.5 },
    ],
  });
};
```

### Perform an Android haptic effect

Perform a semantic Android haptic feedback effect that respects the user's haptic feedback settings. Only available on Android:

```
import { AndroidHapticType, Haptics } from '@capawesome/capacitor-haptics';

const performAndroidHaptic = async () => {
  await Haptics.performAndroidHaptic({ type: AndroidHapticType.Confirm });
};
```

### Vibrate the device

Vibrate the device. The `duration` option is only available on Android and Web:

```
import { Haptics } from '@capawesome/capacitor-haptics';

const vibrate = async () => {
  await Haptics.vibrate({ duration: 500 });
};
```

## API

- [`impact(...)`](#impact)
- [`isAvailable()`](#isavailable)
- [`notification(...)`](#notification)
- [`performAndroidHaptic(...)`](#performandroidhaptic)
- [`playPattern(...)`](#playpattern)
- [`selectionChanged()`](#selectionchanged)
- [`selectionEnd()`](#selectionend)
- [`selectionStart()`](#selectionstart)
- [`vibrate(...)`](#vibrate)
- [Interfaces](#interfaces)
- [Enums](#enums)

### impact(...)

```
impact(options?: ImpactOptions | undefined) => Promise<void>
```

Trigger an impact haptic feedback.

Use this to simulate a physical impact, for example when user interface elements collide or a drag operation snaps into place.

On Android, the impact style is mapped to a best-effort vibration effect.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `ImpactOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if haptic feedback is available on the device.

On Android, this checks whether the device has a vibrator. On iOS, this checks whether the device supports haptic event playback. On the web, this checks whether the Vibration API is supported.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### notification(...)

```
notification(options?: NotificationOptions | undefined) => Promise<void>
```

Trigger a notification haptic feedback.

Use this to communicate that a task or action has succeeded, failed, or produced a warning.

On Android, the notification type is mapped to a best-effort vibration effect.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `NotificationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### performAndroidHaptic(...)

```
performAndroidHaptic(options: PerformAndroidHapticOptions) => Promise<void>
```

Perform a predefined Android haptic feedback effect.

In contrast to the other methods, this method does not use the vibrator but the semantic haptic feedback constants of the Android view system. This respects the user's haptic feedback settings.

Only available on Android.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `PerformAndroidHapticOptions` |

**Since:** 0.1.0

______________________________________________________________________

### playPattern(...)

```
playPattern(options: PlayPatternOptions) => Promise<void>
```

Play a custom haptic pattern composed of individual haptic events.

On iOS, the pattern is played using Core Haptics with full support for intensity and sharpness. This requires a device with haptic event playback support (for example an iPhone with a Taptic Engine). Otherwise, the call rejects as unavailable.

On Android, the pattern is played using vibration effects. Intensity is only respected on devices with amplitude control.

On the web, the pattern is approximated using the Vibration API.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `PlayPatternOptions` |

**Since:** 0.1.0

______________________________________________________________________

### selectionChanged()

```
selectionChanged() => Promise<void>
```

Trigger a selection changed haptic feedback.

Call this method after `selectionStart()` whenever the selection changes.

On the web, this method does nothing.

**Since:** 0.1.0

______________________________________________________________________

### selectionEnd()

```
selectionEnd() => Promise<void>
```

End a selection session.

Call this method when the user finishes a selection interaction.

On the web, this method does nothing.

**Since:** 0.1.0

______________________________________________________________________

### selectionStart()

```
selectionStart() => Promise<void>
```

Start a selection session.

Call this method when the user starts a selection interaction, for example when a picker starts scrolling. It prepares the haptic hardware to reduce the latency of subsequent `selectionChanged()` calls.

On the web, this method does nothing.

**Since:** 0.1.0

______________________________________________________________________

### vibrate(...)

```
vibrate(options?: VibrateOptions | undefined) => Promise<void>
```

Vibrate the device.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `VibrateOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ImpactOptions

| Prop        | Type          | Description              | Default              | Since |
| ----------- | ------------- | ------------------------ | -------------------- | ----- |
| **`style`** | `ImpactStyle` | The style of the impact. | `ImpactStyle.Medium` | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                                | Since |
| --------------- | --------- | ---------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not haptic feedback is available on the device. | 0.1.0 |

#### NotificationOptions

| Prop       | Type               | Description                   | Default                    | Since |
| ---------- | ------------------ | ----------------------------- | -------------------------- | ----- |
| **`type`** | `NotificationType` | The type of the notification. | `NotificationType.Success` | 0.1.0 |

#### PerformAndroidHapticOptions

| Prop       | Type                | Description                                    | Since |
| ---------- | ------------------- | ---------------------------------------------- | ----- |
| **`type`** | `AndroidHapticType` | The Android haptic feedback effect to perform. | 0.1.0 |

#### PlayPatternOptions

| Prop         | Type            | Description                                 | Since |
| ------------ | --------------- | ------------------------------------------- | ----- |
| **`events`** | `HapticEvent[]` | The haptic events that make up the pattern. | 0.1.0 |

#### HapticEvent

| Prop            | Type     | Description                                                                                                                                                                                             | Default | Since |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`duration`**  | `number` | The duration of the event in seconds. If omitted, the event is a transient tap.                                                                                                                         |         | 0.1.0 |
| **`intensity`** | `number` | The intensity of the event as a value between `0` and `1`. On Android, the intensity is only respected on devices with amplitude control.                                                               |         | 0.1.0 |
| **`sharpness`** | `number` | The sharpness of the event as a value between `0` and `1`. A lower value results in a rounder, softer feedback while a higher value results in a crisper, more precise feedback. Only available on iOS. | `0.5`   | 0.1.0 |
| **`time`**      | `number` | The relative time at which the event occurs, in seconds.                                                                                                                                                |         | 0.1.0 |

#### VibrateOptions

| Prop           | Type     | Description                                                                       | Default | Since |
| -------------- | -------- | --------------------------------------------------------------------------------- | ------- | ----- |
| **`duration`** | `number` | The duration of the vibration in milliseconds. Only available on Android and Web. | `300`   | 0.1.0 |

### Enums

#### ImpactStyle

| Members      | Value      | Description                                                     | Since |
| ------------ | ---------- | --------------------------------------------------------------- | ----- |
| **`Heavy`**  | `'HEAVY'`  | A collision between large, heavy user interface elements.       | 0.1.0 |
| **`Light`**  | `'LIGHT'`  | A collision between small, light user interface elements.       | 0.1.0 |
| **`Medium`** | `'MEDIUM'` | A collision between moderately sized user interface elements.   | 0.1.0 |
| **`Rigid`**  | `'RIGID'`  | A collision between hard or inflexible user interface elements. | 0.1.0 |
| **`Soft`**   | `'SOFT'`   | A collision between soft or flexible user interface elements.   | 0.1.0 |

#### NotificationType

| Members       | Value       | Description                                  | Since |
| ------------- | ----------- | -------------------------------------------- | ----- |
| **`Error`**   | `'ERROR'`   | A task or action has failed.                 | 0.1.0 |
| **`Success`** | `'SUCCESS'` | A task or action has completed successfully. | 0.1.0 |
| **`Warning`** | `'WARNING'` | A task or action has produced a warning.     | 0.1.0 |

#### AndroidHapticType

| Members            | Value             | Description                                                                                                               | Since |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ClockTick`**    | `'CLOCK_TICK'`    | The user has pressed either an hour or minute tick of a clock.                                                            | 0.1.0 |
| **`Confirm`**      | `'CONFIRM'`       | The confirmation of a user's action. On Android 10 and older, `ContextClick` is performed instead.                        | 0.1.0 |
| **`ContextClick`** | `'CONTEXT_CLICK'` | The user has performed a context click on an object.                                                                      | 0.1.0 |
| **`KeyboardTap`**  | `'KEYBOARD_TAP'`  | The user has pressed a virtual or software keyboard key.                                                                  | 0.1.0 |
| **`LongPress`**    | `'LONG_PRESS'`    | The user has performed a long press on an object.                                                                         | 0.1.0 |
| **`Reject`**       | `'REJECT'`        | The rejection or failure of a user's action. On Android 10 and older, `LongPress` is performed instead.                   | 0.1.0 |
| **`ToggleOff`**    | `'TOGGLE_OFF'`    | The user has toggled a switch or button into the off position. On Android 13 and older, `ClockTick` is performed instead. | 0.1.0 |
| **`ToggleOn`**     | `'TOGGLE_ON'`     | The user has toggled a switch or button into the on position. On Android 13 and older, `ClockTick` is performed instead.  | 0.1.0 |
| **`VirtualKey`**   | `'VIRTUAL_KEY'`   | The user has pressed on a virtual on-screen key.                                                                          | 0.1.0 |

## Migrating from `@capacitor/haptics`

This plugin is a drop-in replacement for the official `@capacitor/haptics` plugin with a few differences:

| `@capacitor/haptics`                             | Haptics                                                      |
| ------------------------------------------------ | ------------------------------------------------------------ |
| `impact()` (defaults to `ImpactStyle.Heavy`)     | `impact()` (defaults to `ImpactStyle.Medium`)                |
| `impact({ style })` (`Heavy`, `Medium`, `Light`) | `impact({ style })` (plus the new `Rigid` and `Soft` styles) |
| `notification({ type })`                         | `notification({ type })`                                     |
| `vibrate({ duration })`                          | `vibrate({ duration })`                                      |
| `selectionStart()`                               | `selectionStart()`                                           |
| `selectionChanged()`                             | `selectionChanged()`                                         |
| `selectionEnd()`                                 | `selectionEnd()`                                             |
| —                                                | `isAvailable()`                                              |
| —                                                | `performAndroidHaptic({ type })`                             |
| —                                                | `playPattern({ events })`                                    |

**Attention**: The default impact style changed from `ImpactStyle.Heavy` to `ImpactStyle.Medium`. If you rely on the old default, pass `ImpactStyle.Heavy` explicitly.

## Platform behavior

The haptic capabilities of the platforms differ. This plugin maps every method to the best available platform API:

| Method                      | Android                                     | iOS                                        | Web           |
| --------------------------- | ------------------------------------------- | ------------------------------------------ | ------------- |
| `impact(...)`               | Predefined or tuned vibration effects       | `UIImpactFeedbackGenerator` (all 5 styles) | Vibration API |
| `notification(...)`         | Tuned vibration waveforms                   | `UINotificationFeedbackGenerator`          | Vibration API |
| `selection*()`              | Tick vibration effect                       | `UISelectionFeedbackGenerator`             | No-op         |
| `vibrate(...)`              | Vibrator with custom duration               | System vibration (fixed duration)          | Vibration API |
| `performAndroidHaptic(...)` | Haptic feedback constants (no vibrator)     | Not available                              | Not available |
| `playPattern(...)`          | Vibration effects (composition or waveform) | Core Haptics (intensity and sharpness)     | Vibration API |

Custom haptic patterns are strongest on iOS, where Core Haptics supports per-event intensity and sharpness. On Android, patterns are approximated using vibration effect primitives (Android 11+ with supported hardware) or amplitude-controlled waveforms. On the web, patterns are approximated using the Vibration API, which only supports on/off timings.

## FAQ

### How is this plugin different from other similar plugins?

It covers the full range of haptic feedback through one fully typed API: impacts with five styles including the modern Rigid and Soft, notification and selection feedback, custom patterns with per-event intensity and sharpness via Core Haptics on iOS, semantic Android effects that respect the user's system settings, and an availability check — consistently across Android, iOS, and best-effort Web. It is actively maintained against the latest Capacitor and OS versions. If you only need a simple vibration, a minimal setup is fine; if you want rich, platform-aware haptics, this plugin is designed for exactly that.

### How is this plugin different from the official Capacitor Haptics plugin?

This plugin is a drop-in replacement for the official `@capacitor/haptics` plugin with additional features: an `isAvailable()` method, semantic Android haptic effects via `performAndroidHaptic(...)`, custom haptic patterns via `playPattern(...)`, and the modern `Rigid` and `Soft` impact styles. Note that the default impact style is `ImpactStyle.Medium` instead of `ImpactStyle.Heavy`, see [Migrating from `@capacitor/haptics`](#migrating-from-capacitorhaptics).

### Do I need to configure any permissions?

No, the plugin already declares the `android.permission.VIBRATE` permission in its own manifest, so no additional configuration is required on Android. On iOS and Web, no configuration is required either.

### Why don't I feel any haptic feedback on my device?

First, use the `isAvailable()` method to check whether haptic feedback is available: on Android it checks whether the device has a vibrator, on iOS whether the device supports haptic event playback, and on the web whether the Vibration API is supported. Also keep in mind that on Android, the intensity of haptic events is only respected on devices with amplitude control, and that `performAndroidHaptic(...)` respects the user's haptic feedback settings.

### Are custom haptic patterns supported on all platforms?

Custom patterns are strongest on iOS, where Core Haptics supports per-event intensity and sharpness; this requires a device with haptic event playback support (for example an iPhone with a Taptic Engine), otherwise the call rejects as unavailable. On Android, patterns are approximated using vibration effect primitives or amplitude-controlled waveforms. On the web, patterns are approximated using the Vibration API, which only supports on/off timings.

### What is the difference between `vibrate` and `playPattern`?

The `vibrate(...)` method triggers a single vibration with a custom duration, whereby the duration is only respected on Android and Web (on iOS, a system vibration with a fixed duration is played). The `playPattern(...)` method plays a sequence of individual haptic events, each with its own time, intensity, sharpness, and duration.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Shake](https://capawesome.io/docs/sdks/capacitor/shake/): Detect shake gestures, for example to respond with haptic feedback.
- [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/): Detect whether the device is in silent mode.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/haptics/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/haptics/LICENSE).

# Capacitor Health Plugin

Capacitor plugin to read, write and aggregate health data via Apple HealthKit and Android Health Connect with a single, strictly typed API.

## Features

The Capacitor Health plugin connects your app to Apple Health (HealthKit) on iOS and Health Connect on Android. Here are some of the key features:

- 🏥 **Cross-Platform**: One API for Apple HealthKit and Android Health Connect.
- 📖 **~20 Data Types**: Steps, distance, calories, heart rate, sleep, blood pressure, blood glucose, workouts and more.
- 📊 **Aggregation-First**: Query sums, averages, minimums and maximums grouped by hour, day, week or month — with multi-source deduplication handled by the platform.
- ✍️ **Writing**: Log the record types apps commonly write, such as weight, hydration, blood pressure and workouts.
- 🔒 **Honest Permission Model**: Faithfully models what each platform actually reveals about permissions instead of pretending (see the FAQ).
- 🧭 **Availability Handling**: Explicitly models the Health Connect installation states and provides an install helper.
- 📋 **Policy Documentation**: Detailed guidance for the Google Play Health apps declaration and Apple's App Review Guideline 5.1.3.
- 🛡️ **Typed Errors**: Invalid queries reject with clear error codes instead of resolving with silently empty results.
- 🤝 **Compatibility**: Works hand in hand with the [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/), [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) and [Local Notifications](https://capacitorjs.com/docs/apis/local-notifications) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Health plugin is typically used whenever an app works with health and fitness data, for example:

- **Fitness dashboards**: Show daily steps, distance and calories with hourly or daily breakdowns.
- **Workout tracking**: Read workouts from other apps or log your own workout sessions.
- **Health logging**: Let users log weight, hydration, blood pressure or blood glucose.
- **Sleep insights**: Analyze sleep sessions and sleep stages.
- **Coaching and habit apps**: Reward users based on their real activity data.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [Announcing the Capacitor Health Plugin](https://capawesome.io/blog/announcing-the-capacitor-health-plugin/): A tour of the plugin's aggregation-first API, permission model, and app review guidance.
- [Migrating from Google Fit to Health Connect in Capacitor](https://capawesome.io/blog/google-fit-to-health-connect-migration-in-capacitor/): Data type mapping and migration steps before the Google Fit APIs shut down at the end of 2026.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-health` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-health
npx cap sync
```

### Android

The plugin uses [Health Connect](https://health.google/health-connect-android/), Google's platform for health data on Android. Health data is available on devices running Android 9 (API level 28) or higher. On Android 9 to 13, the user may need to install the Health Connect app first (see `isAvailable()` and `installHealthConnect()`). On Android 14 and higher, Health Connect is part of the operating system.

#### Minimum SDK Version

The Health Connect SDK requires a minimum SDK version of `26`. Make sure that the `minSdkVersion` in your `android/variables.gradle` file is set to at least `26`:

```
ext {
    minSdkVersion = 26
}
```

On devices below Android 9, `isAvailable()` resolves with the reason `not-supported` and all other methods reject as unavailable.

#### Permissions

Health Connect permissions are declared **in your app**, not by the plugin. This is intentional: Google Play reviews every declared health permission, so your app must only declare the permissions for the data types it actually uses.

Add the permissions for the data types you use to your `AndroidManifest.xml` file before or after the `application` tag:

```
<!-- Add ONLY the permissions for the data types your app actually uses! -->
<uses-permission android:name="android.permission.health.READ_STEPS" />
<uses-permission android:name="android.permission.health.READ_HEART_RATE" />
<uses-permission android:name="android.permission.health.WRITE_WEIGHT" />
```

The following table lists the permission for each data type supported by this plugin:

| Data Type                | Read Permission                                                                                                                                              | Write Permission (only if you write)                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACTIVE_CALORIES`        | `android.permission.health.READ_ACTIVE_CALORIES_BURNED`                                                                                                      | -                                                                                                                                                |
| `BLOOD_GLUCOSE`          | `android.permission.health.READ_BLOOD_GLUCOSE`                                                                                                               | `android.permission.health.WRITE_BLOOD_GLUCOSE`                                                                                                  |
| `BLOOD_PRESSURE`         | `android.permission.health.READ_BLOOD_PRESSURE`                                                                                                              | `android.permission.health.WRITE_BLOOD_PRESSURE`                                                                                                 |
| `BODY_FAT`               | `android.permission.health.READ_BODY_FAT`                                                                                                                    | -                                                                                                                                                |
| `BODY_TEMPERATURE`       | `android.permission.health.READ_BODY_TEMPERATURE`                                                                                                            | -                                                                                                                                                |
| `DISTANCE`               | `android.permission.health.READ_DISTANCE`                                                                                                                    | -                                                                                                                                                |
| `FLOORS_CLIMBED`         | `android.permission.health.READ_FLOORS_CLIMBED`                                                                                                              | -                                                                                                                                                |
| `HEART_RATE`             | `android.permission.health.READ_HEART_RATE`                                                                                                                  | -                                                                                                                                                |
| `HEART_RATE_VARIABILITY` | `android.permission.health.READ_HEART_RATE_VARIABILITY`                                                                                                      | -                                                                                                                                                |
| `HEIGHT`                 | `android.permission.health.READ_HEIGHT`                                                                                                                      | `android.permission.health.WRITE_HEIGHT`                                                                                                         |
| `HYDRATION`              | `android.permission.health.READ_HYDRATION`                                                                                                                   | `android.permission.health.WRITE_HYDRATION`                                                                                                      |
| `OXYGEN_SATURATION`      | `android.permission.health.READ_OXYGEN_SATURATION`                                                                                                           | -                                                                                                                                                |
| `RESPIRATORY_RATE`       | `android.permission.health.READ_RESPIRATORY_RATE`                                                                                                            | -                                                                                                                                                |
| `RESTING_HEART_RATE`     | `android.permission.health.READ_RESTING_HEART_RATE`                                                                                                          | -                                                                                                                                                |
| `SLEEP`                  | `android.permission.health.READ_SLEEP`                                                                                                                       | -                                                                                                                                                |
| `STEPS`                  | `android.permission.health.READ_STEPS`                                                                                                                       | `android.permission.health.WRITE_STEPS`                                                                                                          |
| `TOTAL_CALORIES`         | `android.permission.health.READ_TOTAL_CALORIES_BURNED`                                                                                                       | -                                                                                                                                                |
| `VO2_MAX`                | `android.permission.health.READ_VO2_MAX`                                                                                                                     | -                                                                                                                                                |
| `WEIGHT`                 | `android.permission.health.READ_WEIGHT`                                                                                                                      | `android.permission.health.WRITE_WEIGHT`                                                                                                         |
| `WORKOUT`                | `android.permission.health.READ_EXERCISE` (optionally `android.permission.health.READ_ACTIVE_CALORIES_BURNED` and `android.permission.health.READ_DISTANCE`) | `android.permission.health.WRITE_EXERCISE`, `android.permission.health.WRITE_DISTANCE`, `android.permission.health.WRITE_ACTIVE_CALORIES_BURNED` |

**Note**: Writing a workout requires three permissions because the plugin writes the optional workout totals (`totalDistance`, `totalCalories`) as separate distance and active calories records, which is how Health Connect models workout totals. For the same reason, `readWorkouts(...)` only returns the workout totals if the read permissions for active calories and distance are granted. Without them, the totals are `null`.

#### Privacy Policy

Health Connect **requires** every app to explain how it uses health data. The plugin already ships the required activity that handles the privacy policy intents of Health Connect. You only need to configure the URL of your privacy policy by adding the following `meta-data` element inside the `application` tag of your `AndroidManifest.xml` file:

```
<meta-data
    android:name="io.capawesome.capacitorjs.plugins.health.PRIVACY_POLICY_URL"
    android:value="https://example.com/privacy-policy" />
```

When the user taps the privacy policy link in the Health Connect permission dialog or in the Health Connect settings, this URL is opened in the browser.

#### Google Play Health Apps Declaration

Google Play requires **every** app that integrates with Health Connect to be approved for access. Without this approval, your app **will be rejected** during Google Play review. Follow these steps before you submit your app:

1. Open the [Google Play Console](https://play.google.com/console/) and select your app.
1. Go to **Monitor and improve** → **Policy and programs** → **App content**.
1. Complete the **Health apps** declaration form: declare that your app integrates with Health Connect, select the requested permission types and describe your use case.
1. Make sure your app provides a **privacy policy** that explains how health data is used (see above).
1. Wait for the approval before rolling out your release.

Health Connect data may only be used for the permitted health use cases described in the [Health Connect policy](https://support.google.com/googleplay/android-developer/answer/12991134). Using health data for advertising or undisclosed data-mining purposes is prohibited and will get your app rejected or removed.

#### Variables

If needed, you can define the following project variables in your app’s `variables.gradle` file to change the default versions of the dependencies:

- `$healthConnectVersion` version of `androidx.health.connect:connect-client` (default: `1.1.0`)
- `$kotlinVersion` version of `org.jetbrains.kotlin:kotlin-gradle-plugin` (default: `2.1.20`)
- `$kotlinxCoroutinesVersion` version of `org.jetbrains.kotlinx:kotlinx-coroutines-android` (default: `1.10.2`)

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

The Health Connect SDK is a lightweight client library. The actual health data store is provided by the Health Connect app (Android 9 to 13) or the operating system (Android 14+) and is **not** bundled with your app.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

The plugin uses [HealthKit](https://developer.apple.com/documentation/healthkit), Apple's framework for health data on iOS. Health data is not available on iPadOS versions before 17 and in visionOS; use `isAvailable()` to check at runtime.

#### Capability

Add the **HealthKit** capability to your app in Xcode: select your app target, open the **Signing & Capabilities** tab and add the **HealthKit** capability. This adds the `com.apple.developer.healthkit` entitlement to your app.

#### Privacy Descriptions

Add the following keys to the `Info.plist` file of your app to explain why your app needs access to health data:

```
<key>NSHealthShareUsageDescription</key>
<string>The app needs access to your health data to show your activity and progress.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>The app writes the health data you log back to Apple Health.</string>
```

`NSHealthShareUsageDescription` is required for reading and `NSHealthUpdateUsageDescription` is required for writing. **Attention**: If a required key is missing, requesting authorization would crash your app. The plugin therefore pre-checks the `Info.plist` file and rejects `requestPermissions(...)` with a clear error message instead.

#### App Review Guideline 5.1.3

Apple reviews health apps against [App Review Guideline 5.1.3 (Health and Health Research)](https://developer.apple.com/app-store/review/guidelines/#health-and-health-research). The most important rules:

- Your app must provide a **genuine health or fitness feature** that justifies the HealthKit integration. Requesting health permissions without a visible feature is a common rejection reason.
- Health data may **not** be used for advertising, marketing or other use-based data mining. Serving ads based on health data will get your app rejected.
- Health data may **not** be shared with third parties without explicit user consent, and never for advertising purposes.
- Apps that write data to HealthKit must ensure the data is **accurate** and clearly attributed.
- Provide a **privacy policy** that explains how health data is collected and used.

## Configuration

No configuration required for this plugin.

## Platform Behavior

The two platforms model health data differently. The plugin exposes these differences honestly instead of hiding them:

| Behavior                 | Android (Health Connect)                                                                                                                                       | iOS (HealthKit)                                                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Availability             | Three states: available, Health Connect not installed (installable via `installHealthConnect()`) or unsupported device.                                        | Available on devices with health data support (`HKHealthStore.isHealthDataAvailable()`).                                                                |
| Read permissions         | Reported as `granted` or `prompt` (`denied` after a rejected request). `checkPermissions(...)` never reports `denied` since Health Connect does not reveal it. | Reported as `prompt` before the first request and `unknown` afterwards. HealthKit deliberately hides read permission status (see FAQ). Never `granted`. |
| Write permissions        | Reported as `granted` or `prompt` (`denied` after a rejected request).                                                                                         | Reported as `granted`, `denied` or `prompt`.                                                                                                            |
| Historical reads         | Limited to 30 days before the permission was first granted.                                                                                                    | No time limit.                                                                                                                                          |
| `SLEEP` records          | Sleep sessions containing all sleep stages.                                                                                                                    | Individual sleep analysis samples, each with exactly one stage (HealthKit has no session concept).                                                      |
| `TOTAL_CALORIES`         | Dedicated total calories record type.                                                                                                                          | Only available via `aggregate(...)`, computed as active + basal energy burned.                                                                          |
| `HEART_RATE_VARIABILITY` | RMSSD metric.                                                                                                                                                  | SDNN metric. **The values are not comparable across platforms!**                                                                                        |
| Workout totals           | Aggregated from the records the workout app wrote for the workout time range.                                                                                  | Read from the workout statistics (iOS 16+; `null` on earlier versions).                                                                                 |
| `sourceName`             | Not provided by Health Connect (always `null`). Use `sourceBundleId`.                                                                                          | The display name of the source (e.g. "Apple Watch").                                                                                                    |

## Usage

```
import { DataType, Health } from '@capawesome-team/capacitor-health';

const checkAvailability = async () => {
  const { available, reason } = await Health.isAvailable();
  if (!available && reason === 'health-connect-not-installed') {
    // Prompt the user to install Health Connect (Android 9 to 13)
    await Health.installHealthConnect();
  }
  return available;
};

const requestPermissions = async () => {
  const { permissions } = await Health.requestPermissions({
    read: [DataType.Steps, DataType.HeartRate, DataType.Sleep],
    write: [DataType.Weight],
  });
  return permissions;
};

const readSteps = async () => {
  const { records } = await Health.readRecords({
    dataType: DataType.Steps,
    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
  });
  return records;
};

const aggregateDailySteps = async () => {
  const { buckets } = await Health.aggregate({
    dataType: DataType.Steps,
    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
    bucket: 'day',
    operations: ['sum'],
  });
  return buckets;
};

const readWorkouts = async () => {
  const { workouts } = await Health.readWorkouts({
    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
    limit: 10,
  });
  return workouts;
};

const writeWeight = async () => {
  await Health.writeRecord({
    dataType: DataType.Weight,
    startDate: new Date().toISOString(),
    value: 71.5,
  });
};

const openSettings = async () => {
  await Health.openSettings();
};
```

## API

- [`aggregate(...)`](#aggregate)
- [`checkPermissions(...)`](#checkpermissions)
- [`installHealthConnect()`](#installhealthconnect)
- [`isAvailable()`](#isavailable)
- [`openSettings()`](#opensettings)
- [`readRecords(...)`](#readrecords)
- [`readWorkouts(...)`](#readworkouts)
- [`requestPermissions(...)`](#requestpermissions)
- [`writeRecord(...)`](#writerecord)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### aggregate(...)

```
aggregate(options: AggregateOptions) => Promise<AggregateResult>
```

Aggregate health data over a time range, optionally grouped into buckets.

The aggregation is performed by the platform's health store, which deduplicates overlapping data from multiple sources (e.g. a phone and a smartwatch) automatically.

Only the following combinations of data type and operation are supported:

| Data Type            | `sum` | `average`, `maximum`, `minimum` |
| -------------------- | ----- | ------------------------------- |
| `ACTIVE_CALORIES`    | ✅    | ❌                              |
| `DISTANCE`           | ✅    | ❌                              |
| `FLOORS_CLIMBED`     | ✅    | ❌                              |
| `HEART_RATE`         | ❌    | ✅                              |
| `HEIGHT`             | ❌    | ✅                              |
| `HYDRATION`          | ✅    | ❌                              |
| `RESTING_HEART_RATE` | ❌    | ✅                              |
| `STEPS`              | ✅    | ❌                              |
| `TOTAL_CALORIES`     | ✅    | ❌                              |
| `WEIGHT`             | ❌    | ✅                              |

Any other combination rejects with the `INVALID_AGGREGATION` error code. It never resolves with silently empty results.

On **iOS**, `TOTAL_CALORIES` is computed as the sum of active and basal energy burned since HealthKit has no total energy type.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AggregateOptions` |

**Returns:** `Promise<AggregateResult>`

**Since:** 0.0.1

______________________________________________________________________

### checkPermissions(...)

```
checkPermissions(options: CheckPermissionsOptions) => Promise<PermissionStatus>
```

Check the permission status for the given data types.

On **Android**, Health Connect only reports whether a permission is currently granted. A permission that has never been requested and a permission that has been denied are both reported as `prompt`.

On **iOS**, HealthKit deliberately hides the read permission status to prevent apps from inferring sensitive information (a denied read permission is indistinguishable from the absence of data). Read permissions are therefore reported as `prompt` before the first request and as `unknown` afterwards. They are **never** reported as `granted`. Design your app around the presence of data, not around the read permission status.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `CheckPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### installHealthConnect()

```
installHealthConnect() => Promise<void>
```

Open the Play Store to install or update the Health Connect app.

On Android 9 to 13, Health Connect must be installed as a separate app. On Android 14 and later, Health Connect is part of the operating system but may still require an update.

Call this method if `isAvailable()` returns the reason `health-connect-not-installed` or `health-connect-update-required`.

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether health data is available on the device.

On **Android**, this checks the Health Connect SDK status and reports one of three states: available, not installed (but supported) or unsupported. If Health Connect is not installed, you can prompt the user to install it with `installHealthConnect()`.

On **iOS**, this checks `HKHealthStore.isHealthDataAvailable()`, which returns `false` on devices without health data support (e.g. some iPads).

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.0.1

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the platform's health settings.

On **Android**, this opens the Health Connect settings where the user can manage app permissions and data.

On **iOS**, this opens the Apple Health app. Apple does not provide a way to open the privacy settings of your app directly. The user can manage permissions in the Health app under `Profile → Privacy → Apps`.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### readRecords(...)

```
readRecords(options: ReadRecordsOptions) => Promise<ReadRecordsResult>
```

Read individual health records of a single data type.

On **Android**, reads are limited to the last 30 days before the permission was first granted.

On **iOS**, the `TOTAL_CALORIES` data type is not supported by this method since HealthKit has no total energy type. Use `aggregate(...)` instead.

To read workouts, use `readWorkouts(...)`.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `ReadRecordsOptions` |

**Returns:** `Promise<ReadRecordsResult>`

**Since:** 0.0.1

______________________________________________________________________

### readWorkouts(...)

```
readWorkouts(options: ReadWorkoutsOptions) => Promise<ReadWorkoutsResult>
```

Read workouts.

Requires the read permission for the `WORKOUT` data type.

On **Android**, the `totalCalories` and `totalDistance` values additionally require the read permissions for the `ACTIVE_CALORIES` and `DISTANCE` data types. Without them, both values are `null`.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ReadWorkoutsOptions` |

**Returns:** `Promise<ReadWorkoutsResult>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options: RequestPermissionsOptions) => Promise<PermissionStatus>
```

Request permissions for the given data types.

On **Android**, the Health Connect permission screen is shown. If the user denies the request twice, Health Connect permanently ignores further requests and the permissions can only be granted via `openSettings()`.

On **iOS**, the HealthKit authorization sheet is shown once per data type. After the request, read permissions are reported as `unknown` since HealthKit hides the read permission status (see `checkPermissions(...)`).

On **iOS**, this method rejects with a clear error message if the required usage descriptions are missing in the `Info.plist` file (see the installation instructions).

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### writeRecord(...)

```
writeRecord(options: WriteRecordOptions) => Promise<void>
```

Write a single health record.

Requires the write permission for the given data type.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `WriteRecordOptions` |

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### AggregateResult

| Prop          | Type                      | Description                                    | Since |
| ------------- | ------------------------- | ---------------------------------------------- | ----- |
| **`buckets`** | `AggregateResultBucket[]` | The aggregated buckets in chronological order. | 0.0.1 |

#### AggregateResultBucket

| Prop            | Type                     | Description                                         | Since |
| --------------- | ------------------------ | --------------------------------------------------- | ----- |
| **`endDate`**   | `string`                 | The end of the bucket as ISO 8601 string.           | 0.0.1 |
| **`startDate`** | `string`                 | The start of the bucket as ISO 8601 string.         | 0.0.1 |
| **`values`**    | `AggregateResultValue[]` | The aggregated values for each requested operation. | 0.0.1 |

#### AggregateResultValue

| Prop            | Type                   | Description                             | Since                                                                                                                                              |
| --------------- | ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`operation`** | `AggregationOperation` | The operation that produced this value. | 0.0.1                                                                                                                                              |
| **`value`**     | \`number               | null\`                                  | The aggregated value in the fixed unit of the data type (see [`DataType`](#datatype)). If no data is available in the bucket, the value is `null`. |

#### AggregateOptions

| Prop             | Type                     | Description                                                                                                                                                                                                                                                                                    | Since |
| ---------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bucket`**     | `AggregationBucket`      | The bucket size to group the results by. The buckets are aligned to `startDate`. The `day`, `week` and `month` buckets are calendar-aware (e.g. months have different lengths) and are based on the device's time zone. If `none`, a single bucket spanning the entire time range is returned. | 0.0.1 |
| **`dataType`**   | `DataType`               | The data type to aggregate.                                                                                                                                                                                                                                                                    | 0.0.1 |
| **`endDate`**    | `string`                 | The end of the time range (exclusive) as ISO 8601 string.                                                                                                                                                                                                                                      | 0.0.1 |
| **`operations`** | `AggregationOperation[]` | The operations to perform on the data in each bucket. See `aggregate(...)` for the supported combinations of data type and operation.                                                                                                                                                          | 0.0.1 |
| **`startDate`**  | `string`                 | The start of the time range (inclusive) as ISO 8601 string.                                                                                                                                                                                                                                    | 0.0.1 |

#### PermissionStatus

| Prop              | Type                       | Description                                         | Since |
| ----------------- | -------------------------- | --------------------------------------------------- | ----- |
| **`permissions`** | `HealthPermissionStatus[]` | The permission status for each requested data type. | 0.0.1 |

#### HealthPermissionStatus

| Prop           | Type                    | Description                                                                                | Since |
| -------------- | ----------------------- | ------------------------------------------------------------------------------------------ | ----- |
| **`dataType`** | `DataType`              | The data type this status belongs to.                                                      | 0.0.1 |
| **`read`**     | `HealthPermissionState` | The read permission status. Only set if the data type was included in the `read` option.   | 0.0.1 |
| **`write`**    | `HealthPermissionState` | The write permission status. Only set if the data type was included in the `write` option. | 0.0.1 |

#### CheckPermissionsOptions

| Prop        | Type                 | Description                                              | Since |
| ----------- | -------------------- | -------------------------------------------------------- | ----- |
| **`read`**  | `DataType[]`         | The data types to check the read permission status for.  | 0.0.1 |
| **`write`** | `WritableDataType[]` | The data types to check the write permission status for. | 0.0.1 |

#### IsAvailableResult

| Prop            | Type                | Description                                            | Since                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------- | ------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`available`** | `boolean`           | Whether or not health data is available on the device. | 0.0.1                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **`reason`**    | \`IsAvailableReason | null\`                                                 | The reason why health data is not available on the device. If health data is available, the value is `null`. On **Android**, the reason `health-connect-not-installed` means that the device is supported but the Health Connect app is not installed. Call `installHealthConnect()` to prompt the user to install it. The reason `health-connect-update-required` means that the installed Health Connect app is too old. |

#### ReadRecordsResult

| Prop          | Type             | Description                 | Since |
| ------------- | ---------------- | --------------------------- | ----- |
| **`records`** | `HealthRecord[]` | The records that were read. | 0.0.1 |

#### HealthRecord

A single health record.

| Prop                 | Type                 | Description                                                                                                                                                                                                                                                       | Since                                                                                                                                                                                                                                                                                                                         |
| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`dataType`**       | `DataType`           | The data type of the record.                                                                                                                                                                                                                                      | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`diastolic`**      | `number`             | The diastolic blood pressure in millimeters of mercury. Only set for the `BLOOD_PRESSURE` data type.                                                                                                                                                              | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`endDate`**        | `string`             | The end of the record as ISO 8601 string. For instantaneous records (e.g. weight), this is the same as `startDate`.                                                                                                                                               | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`id`**             | \`string             | null\`                                                                                                                                                                                                                                                            | The unique identifier of the record. If the platform does not provide an identifier, the value is `null`.                                                                                                                                                                                                                     |
| **`sourceBundleId`** | \`string             | null\`                                                                                                                                                                                                                                                            | The bundle identifier (iOS) or package name (Android) of the app that wrote the record.                                                                                                                                                                                                                                       |
| **`sourceName`**     | \`string             | null\`                                                                                                                                                                                                                                                            | The display name of the source that wrote the record. On **Android**, Health Connect does not provide a display name, so the value is always `null`.                                                                                                                                                                          |
| **`stages`**         | `SleepStageSample[]` | The sleep stages of the record. Only set for the `SLEEP` data type. On **Android**, a record is a sleep session that contains all its stages. On **iOS**, HealthKit has no session concept. Each record is a single sleep analysis sample with exactly one stage. | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`startDate`**      | `string`             | The start of the record as ISO 8601 string.                                                                                                                                                                                                                       | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`systolic`**       | `number`             | The systolic blood pressure in millimeters of mercury. Only set for the `BLOOD_PRESSURE` data type.                                                                                                                                                               | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`unit`**           | `string`             | The fixed unit of the value (see [`DataType`](#datatype)).                                                                                                                                                                                                        | 0.0.1                                                                                                                                                                                                                                                                                                                         |
| **`value`**          | \`number             | null\`                                                                                                                                                                                                                                                            | The value of the record in the fixed unit of the data type (see `DataType`). For the `BLOOD_PRESSURE` data type, the value is `null` (see `systolic` and `diastolic`). For the `SLEEP` data type, the value is the duration in minutes. Non-finite values reported by third-party data sources are also normalized to `null`. |

#### SleepStageSample

A single sleep stage within a sleep record.

| Prop            | Type         | Description                                      | Since |
| --------------- | ------------ | ------------------------------------------------ | ----- |
| **`endDate`**   | `string`     | The end of the sleep stage as ISO 8601 string.   | 0.0.1 |
| **`stage`**     | `SleepStage` | The sleep stage.                                 | 0.0.1 |
| **`startDate`** | `string`     | The start of the sleep stage as ISO 8601 string. | 0.0.1 |

#### ReadRecordsOptions

| Prop              | Type       | Description                                                                                                                                                        | Default | Since |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`ascending`**   | `boolean`  | Whether to return the records in ascending order by start date.                                                                                                    | `true`  | 0.0.1 |
| **`dataOrigins`** | `string[]` | Filter the records by the apps that wrote them, identified by bundle identifier (iOS) or package name (Android). An empty array is treated like an omitted filter. |         | 0.0.1 |
| **`dataType`**    | `DataType` | The data type to read. The `WORKOUT` data type is not supported by this method. Use `readWorkouts(...)` instead.                                                   |         | 0.0.1 |
| **`endDate`**     | `string`   | The end of the time range (exclusive) as ISO 8601 string.                                                                                                          |         | 0.0.1 |
| **`limit`**       | `number`   | The maximum number of records to return. If not set, all records in the time range are returned.                                                                   |         | 0.0.1 |
| **`startDate`**   | `string`   | The start of the time range (inclusive) as ISO 8601 string.                                                                                                        |         | 0.0.1 |

#### ReadWorkoutsResult

| Prop           | Type        | Description                  | Since |
| -------------- | ----------- | ---------------------------- | ----- |
| **`workouts`** | `Workout[]` | The workouts that were read. | 0.0.1 |

#### Workout

A single workout.

| Prop                 | Type          | Description                                                                                                                                                                                               | Since                                                                                                                                                                                                                                                |
| -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`duration`**       | `number`      | The duration of the workout in seconds. On **Android**, this is the wall-clock time between `startDate` and `endDate`. On **iOS**, paused intervals are excluded.                                         | 0.0.1                                                                                                                                                                                                                                                |
| **`endDate`**        | `string`      | The end of the workout as ISO 8601 string.                                                                                                                                                                | 0.0.1                                                                                                                                                                                                                                                |
| **`id`**             | \`string      | null\`                                                                                                                                                                                                    | The unique identifier of the workout. If the platform does not provide an identifier, the value is `null`.                                                                                                                                           |
| **`rawWorkoutType`** | \`string      | null\`                                                                                                                                                                                                    | The platform-specific raw workout type. On **Android**, this is the numeric Health Connect exercise type. On **iOS**, this is the numeric `HKWorkoutActivityType` raw value. Use this value to distinguish workout types that are mapped to `OTHER`. |
| **`sourceBundleId`** | \`string      | null\`                                                                                                                                                                                                    | The bundle identifier (iOS) or package name (Android) of the app that wrote the workout.                                                                                                                                                             |
| **`sourceName`**     | \`string      | null\`                                                                                                                                                                                                    | The display name of the source that wrote the workout. On **Android**, Health Connect does not provide a display name, so the value is always `null`.                                                                                                |
| **`startDate`**      | `string`      | The start of the workout as ISO 8601 string.                                                                                                                                                              | 0.0.1                                                                                                                                                                                                                                                |
| **`totalCalories`**  | \`number      | null\`                                                                                                                                                                                                    | The total energy burned during the workout in kilocalories. If the platform does not provide a value, the value is `null`. On **iOS**, the value is only available on iOS 16 and later.                                                              |
| **`totalDistance`**  | \`number      | null\`                                                                                                                                                                                                    | The total distance covered during the workout in meters. If the platform does not provide a value, the value is `null`. On **iOS**, the value is only available on iOS 16 and later.                                                                 |
| **`workoutType`**    | `WorkoutType` | The type of the workout. If the platform-specific workout type has no equivalent in [`WorkoutType`](#workouttype), the value is `OTHER` and the platform-specific value is available in `rawWorkoutType`. | 0.0.1                                                                                                                                                                                                                                                |

#### ReadWorkoutsOptions

| Prop              | Type          | Description                                                                                        | Since |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------- | ----- |
| **`endDate`**     | `string`      | The end of the time range (exclusive) as ISO 8601 string.                                          | 0.0.1 |
| **`limit`**       | `number`      | The maximum number of workouts to return. If not set, all workouts in the time range are returned. | 0.0.1 |
| **`startDate`**   | `string`      | The start of the time range (inclusive) as ISO 8601 string.                                        | 0.0.1 |
| **`workoutType`** | `WorkoutType` | Filter the workouts by workout type.                                                               | 0.0.1 |

#### RequestPermissionsOptions

| Prop        | Type                 | Description                                         | Since |
| ----------- | -------------------- | --------------------------------------------------- | ----- |
| **`read`**  | `DataType[]`         | The data types to request the read permission for.  | 0.0.1 |
| **`write`** | `WritableDataType[]` | The data types to request the write permission for. | 0.0.1 |

#### WriteRecordOptions

| Prop            | Type                 | Description                                                                                                                                                                                     | Since |
| --------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`dataType`**  | `WritableDataType`   | The data type to write.                                                                                                                                                                         | 0.0.1 |
| **`diastolic`** | `number`             | The diastolic blood pressure in millimeters of mercury. Required for the `BLOOD_PRESSURE` data type.                                                                                            | 0.0.1 |
| **`endDate`**   | `string`             | The end of the record as ISO 8601 string. Required for the `HYDRATION`, `STEPS` and `WORKOUT` data types. Ignored for instantaneous data types (e.g. `WEIGHT`).                                 | 0.0.1 |
| **`startDate`** | `string`             | The start of the record as ISO 8601 string.                                                                                                                                                     | 0.0.1 |
| **`systolic`**  | `number`             | The systolic blood pressure in millimeters of mercury. Required for the `BLOOD_PRESSURE` data type.                                                                                             | 0.0.1 |
| **`value`**     | `number`             | The value of the record in the fixed unit of the data type (see `DataType`). Required for the `BLOOD_GLUCOSE`, `HEIGHT`, `HYDRATION`, `STEPS` and `WEIGHT` data types. Must be a finite number. | 0.0.1 |
| **`workout`**   | `WriteRecordWorkout` | The workout to write. Required for the `WORKOUT` data type.                                                                                                                                     | 0.0.1 |

#### WriteRecordWorkout

| Prop                | Type          | Description                                                                                                                                                                                                                         | Since |
| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`totalCalories`** | `number`      | The total energy burned during the workout in kilocalories. On **Android**, this additionally writes an active calories record for the workout time range, which requires the write permission for the `ACTIVE_CALORIES` data type. | 0.0.1 |
| **`totalDistance`** | `number`      | The total distance covered during the workout in meters. On **Android**, this additionally writes a distance record for the workout time range, which requires the write permission for the `DISTANCE` data type.                   | 0.0.1 |
| **`workoutType`**   | `WorkoutType` | The type of the workout. If the platform has no equivalent for the given workout type, it is written as the platform's generic workout type.                                                                                        | 0.0.1 |

### Type Aliases

#### AggregationOperation

The operation to perform when aggregating data.

`'average' | 'maximum' | 'minimum' | 'sum'`

#### AggregationBucket

The bucket size to group aggregation results by.

`'day' | 'hour' | 'month' | 'none' | 'week'`

#### HealthPermissionState

The status of a single health permission.

The value `unknown` is used on iOS for read permissions after the first request since HealthKit deliberately hides whether a read permission was granted or denied.

`'denied' | 'granted' | 'prompt' | 'unknown'`

#### WritableDataType

The data types that can be written with `writeRecord(...)`.

`DataType.BloodGlucose | DataType.BloodPressure | DataType.Height | DataType.Hydration | DataType.Steps | DataType.Weight | DataType.Workout`

#### IsAvailableReason

The reason why health data is not available on the device.

`'health-connect-not-installed' | 'health-connect-update-required' | 'not-supported'`

### Enums

#### DataType

| Members                    | Value                      | Description                                                                                                                                                                                                                                                                                                                               | Since |
| -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ActiveCalories`**       | `'ACTIVE_CALORIES'`        | Active energy burned in kilocalories (`kcal`).                                                                                                                                                                                                                                                                                            | 0.0.1 |
| **`BloodGlucose`**         | `'BLOOD_GLUCOSE'`          | Blood glucose level in millimoles per liter (`mmol/L`).                                                                                                                                                                                                                                                                                   | 0.0.1 |
| **`BloodPressure`**        | `'BLOOD_PRESSURE'`         | Blood pressure in millimeters of mercury (`mmHg`). Records of this data type use the `systolic` and `diastolic` properties instead of `value`.                                                                                                                                                                                            | 0.0.1 |
| **`BodyFat`**              | `'BODY_FAT'`               | Body fat percentage (`percent`, 0 to 100).                                                                                                                                                                                                                                                                                                | 0.0.1 |
| **`BodyTemperature`**      | `'BODY_TEMPERATURE'`       | Body temperature in degrees Celsius (`celsius`).                                                                                                                                                                                                                                                                                          | 0.0.1 |
| **`Distance`**             | `'DISTANCE'`               | Distance covered in meters (`m`). On **iOS**, this maps to walking and running distance.                                                                                                                                                                                                                                                  | 0.0.1 |
| **`FloorsClimbed`**        | `'FLOORS_CLIMBED'`         | Floors climbed (`count`).                                                                                                                                                                                                                                                                                                                 | 0.0.1 |
| **`HeartRate`**            | `'HEART_RATE'`             | Heart rate in beats per minute (`bpm`).                                                                                                                                                                                                                                                                                                   | 0.0.1 |
| **`HeartRateVariability`** | `'HEART_RATE_VARIABILITY'` | Heart rate variability in milliseconds (`ms`). **Attention**: The platforms measure different metrics! Android (Health Connect) provides RMSSD values while iOS (HealthKit) provides SDNN values. The values are exposed as-is and are **not** comparable across platforms.                                                               | 0.0.1 |
| **`Height`**               | `'HEIGHT'`                 | Height in meters (`m`).                                                                                                                                                                                                                                                                                                                   | 0.0.1 |
| **`Hydration`**            | `'HYDRATION'`              | Water intake in liters (`L`).                                                                                                                                                                                                                                                                                                             | 0.0.1 |
| **`OxygenSaturation`**     | `'OXYGEN_SATURATION'`      | Blood oxygen saturation percentage (`percent`, 0 to 100).                                                                                                                                                                                                                                                                                 | 0.0.1 |
| **`RespiratoryRate`**      | `'RESPIRATORY_RATE'`       | Respiratory rate in breaths per minute (`breaths/min`).                                                                                                                                                                                                                                                                                   | 0.0.1 |
| **`RestingHeartRate`**     | `'RESTING_HEART_RATE'`     | Resting heart rate in beats per minute (`bpm`).                                                                                                                                                                                                                                                                                           | 0.0.1 |
| **`Sleep`**                | `'SLEEP'`                  | Sleep sessions with sleep stages. The record value is the duration in minutes (`min`).                                                                                                                                                                                                                                                    | 0.0.1 |
| **`Steps`**                | `'STEPS'`                  | Steps taken (`count`).                                                                                                                                                                                                                                                                                                                    | 0.0.1 |
| **`TotalCalories`**        | `'TOTAL_CALORIES'`         | Total energy burned in kilocalories (`kcal`). **Attention**: The platforms compose this value differently! Android (Health Connect) has a dedicated total calories record type while on iOS (HealthKit) the value is computed as the sum of active and basal energy burned. On iOS, this data type is only supported by `aggregate(...)`. | 0.0.1 |
| **`Vo2Max`**               | `'VO2_MAX'`                | Maximal oxygen consumption in milliliters per kilogram of body weight per minute (`mL/kg/min`).                                                                                                                                                                                                                                           | 0.0.1 |
| **`Weight`**               | `'WEIGHT'`                 | Body weight in kilograms (`kg`).                                                                                                                                                                                                                                                                                                          | 0.0.1 |
| **`Workout`**              | `'WORKOUT'`                | Workouts (exercise sessions). This data type is used for permission requests, `readWorkouts(...)` and `writeRecord(...)`. It is not supported by `readRecords(...)`.                                                                                                                                                                      | 0.0.1 |

#### SleepStage

| Members       | Value       | Description                                      | Since |
| ------------- | ----------- | ------------------------------------------------ | ----- |
| **`Awake`**   | `'AWAKE'`   | The user is awake.                               | 0.0.1 |
| **`Deep`**    | `'DEEP'`    | The user is in deep sleep.                       | 0.0.1 |
| **`InBed`**   | `'IN_BED'`  | The user is in bed but not necessarily sleeping. | 0.0.1 |
| **`Light`**   | `'LIGHT'`   | The user is in light sleep.                      | 0.0.1 |
| **`Rem`**     | `'REM'`     | The user is in REM sleep.                        | 0.0.1 |
| **`Unknown`** | `'UNKNOWN'` | The sleep stage is unknown.                      | 0.0.1 |

#### WorkoutType

| Members                             | Value                                | Description                                                                                                                                                                  | Since |
| ----------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`AmericanFootball`**              | `'AMERICAN_FOOTBALL'`                |                                                                                                                                                                              | 0.0.1 |
| **`AustralianFootball`**            | `'AUSTRALIAN_FOOTBALL'`              |                                                                                                                                                                              | 0.0.1 |
| **`Badminton`**                     | `'BADMINTON'`                        |                                                                                                                                                                              | 0.0.1 |
| **`Baseball`**                      | `'BASEBALL'`                         |                                                                                                                                                                              | 0.0.1 |
| **`Basketball`**                    | `'BASKETBALL'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Biking`**                        | `'BIKING'`                           |                                                                                                                                                                              | 0.0.1 |
| **`Boxing`**                        | `'BOXING'`                           |                                                                                                                                                                              | 0.0.1 |
| **`Calisthenics`**                  | `'CALISTHENICS'`                     | On **iOS**, this is written as functional strength training and read as `STRENGTH_TRAINING`.                                                                                 | 0.0.1 |
| **`Cricket`**                       | `'CRICKET'`                          |                                                                                                                                                                              | 0.0.1 |
| **`Dancing`**                       | `'DANCING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`Elliptical`**                    | `'ELLIPTICAL'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Fencing`**                       | `'FENCING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`Golf`**                          | `'GOLF'`                             |                                                                                                                                                                              | 0.0.1 |
| **`Gymnastics`**                    | `'GYMNASTICS'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Handball`**                      | `'HANDBALL'`                         |                                                                                                                                                                              | 0.0.1 |
| **`HighIntensityIntervalTraining`** | `'HIGH_INTENSITY_INTERVAL_TRAINING'` |                                                                                                                                                                              | 0.0.1 |
| **`Hiking`**                        | `'HIKING'`                           |                                                                                                                                                                              | 0.0.1 |
| **`IceHockey`**                     | `'ICE_HOCKEY'`                       |                                                                                                                                                                              | 0.0.1 |
| **`IceSkating`**                    | `'ICE_SKATING'`                      |                                                                                                                                                                              | 0.0.1 |
| **`MartialArts`**                   | `'MARTIAL_ARTS'`                     |                                                                                                                                                                              | 0.0.1 |
| **`Other`**                         | `'OTHER'`                            |                                                                                                                                                                              | 0.0.1 |
| **`Paddling`**                      | `'PADDLING'`                         |                                                                                                                                                                              | 0.0.1 |
| **`Pilates`**                       | `'PILATES'`                          |                                                                                                                                                                              | 0.0.1 |
| **`Racquetball`**                   | `'RACQUETBALL'`                      |                                                                                                                                                                              | 0.0.1 |
| **`RockClimbing`**                  | `'ROCK_CLIMBING'`                    |                                                                                                                                                                              | 0.0.1 |
| **`Rowing`**                        | `'ROWING'`                           |                                                                                                                                                                              | 0.0.1 |
| **`RowingMachine`**                 | `'ROWING_MACHINE'`                   | On **iOS**, this is written and read as `ROWING`.                                                                                                                            | 0.0.1 |
| **`Rugby`**                         | `'RUGBY'`                            |                                                                                                                                                                              | 0.0.1 |
| **`Running`**                       | `'RUNNING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`RunningTreadmill`**              | `'RUNNING_TREADMILL'`                | On **iOS**, this is written and read as `RUNNING`.                                                                                                                           | 0.0.1 |
| **`Sailing`**                       | `'SAILING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`ScubaDiving`**                   | `'SCUBA_DIVING'`                     |                                                                                                                                                                              | 0.0.1 |
| **`Skiing`**                        | `'SKIING'`                           |                                                                                                                                                                              | 0.0.1 |
| **`Snowboarding`**                  | `'SNOWBOARDING'`                     |                                                                                                                                                                              | 0.0.1 |
| **`Soccer`**                        | `'SOCCER'`                           |                                                                                                                                                                              | 0.0.1 |
| **`Softball`**                      | `'SOFTBALL'`                         |                                                                                                                                                                              | 0.0.1 |
| **`Squash`**                        | `'SQUASH'`                           |                                                                                                                                                                              | 0.0.1 |
| **`StairClimbing`**                 | `'STAIR_CLIMBING'`                   |                                                                                                                                                                              | 0.0.1 |
| **`StrengthTraining`**              | `'STRENGTH_TRAINING'`                |                                                                                                                                                                              | 0.0.1 |
| **`Stretching`**                    | `'STRETCHING'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Surfing`**                       | `'SURFING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`Swimming`**                      | `'SWIMMING'`                         | Generic swimming (iOS only). On **Android**, this is written as the generic workout type. Use `SWIMMING_POOL` or `SWIMMING_OPEN_WATER` for cross-platform swimming workouts. | 0.0.1 |
| **`SwimmingOpenWater`**             | `'SWIMMING_OPEN_WATER'`              | On **iOS**, this is written and read as `SWIMMING`.                                                                                                                          | 0.0.1 |
| **`SwimmingPool`**                  | `'SWIMMING_POOL'`                    | On **iOS**, this is written and read as `SWIMMING`.                                                                                                                          | 0.0.1 |
| **`TableTennis`**                   | `'TABLE_TENNIS'`                     |                                                                                                                                                                              | 0.0.1 |
| **`Tennis`**                        | `'TENNIS'`                           |                                                                                                                                                                              | 0.0.1 |
| **`Volleyball`**                    | `'VOLLEYBALL'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Walking`**                       | `'WALKING'`                          |                                                                                                                                                                              | 0.0.1 |
| **`WaterPolo`**                     | `'WATER_POLO'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Wheelchair`**                    | `'WHEELCHAIR'`                       |                                                                                                                                                                              | 0.0.1 |
| **`Yoga`**                          | `'YOGA'`                             |                                                                                                                                                                              | 0.0.1 |

## FAQ

### How is this plugin different from other similar plugins?

It is built for correctness and honesty with health data: it reports iOS permission states accurately, surfaces the real availability states on Android, and returns strongly-typed, aggregation-first results. It also ships the setup and policy documentation you need to pass App Review and the required Google Play health-data declaration — the steps that most often decide whether a health app ships — and it's backed by dedicated support.

### Why are read permissions reported as `unknown` on iOS?

HealthKit deliberately hides whether a read permission was granted or denied to prevent apps from inferring sensitive information (an app that knows it was denied access to, say, blood glucose data could conclude the user is likely diabetic). A denied read permission behaves exactly like the absence of data. Some plugins pretend read permissions are `granted` after a request — this plugin does not, because it would simply be wrong. Design your app around the **presence of data**, not around the read permission status: request the permissions, query the data and show an appropriate empty state (e.g. "No data available. Check the Health app if you expected data here.") when nothing is returned.

### Why does my app get rejected by Google Play?

Every app that integrates with Health Connect must complete the **Health apps declaration** in the Google Play Console and be approved for the requested permission types (see the installation instructions above). Also make sure your app only declares the health permissions it actually uses and provides a privacy policy.

### Why can't I read data older than 30 days on Android?

Health Connect only allows apps to read data from up to 30 days before the moment the permission was first granted. If the permission is revoked and granted again, the 30-day window is calculated from the new grant. Support for the `READ_HEALTH_DATA_HISTORY` permission is planned as a fast-follow feature.

### Is health data available on the web?

No. There is no web API for health data. All methods reject with an unimplemented error on the web.

### Why do steps from my phone and smartwatch not add up?

They do — that's the point of `aggregate(...)`. The platform deduplicates overlapping data from multiple sources automatically. If you sum up the individual records from `readRecords(...)` yourself, you will count overlapping data twice. Use `aggregate(...)` for totals.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/): Live step counting from the device's motion sensors.
- [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/): Track workout routes in the background.
- [Local Notifications](https://capacitorjs.com/docs/apis/local-notifications): Remind users to log their health data.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/LICENSE).

# Capacitor Home Indicator Plugin

Capacitor plugin to hide and show the iOS [home indicator](https://developer.apple.com/documentation/uikit/uiviewcontroller/prefershomeindicatorautohidden).

## Features

- 🫥 **Hide & show**: Hide and show the home indicator at runtime.
- 🔍 **State**: Read the current plugin-managed state.
- 🧩 **Zero-config**: No changes to your native project required.
- 🤝 **Compatibility**: Need to control the Android navigation bar? Use the [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Home Indicator plugin is typically used to reduce visual distraction in fullscreen experiences on iOS, for example:

- **Video players**: Hide the home indicator while a video is playing so it fades out when the screen is idle.
- **Games**: Keep the focus on the gameplay by letting the home indicator auto-hide.
- **Reading modes**: Provide a distraction-free reading experience for articles, books, or documents.
- **Kiosk-style apps**: Minimize on-screen system UI for apps running in a presentation or kiosk context.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-home-indicator` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-home-indicator
npx cap sync
```

This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented. To control the navigation bar on Android, use the [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/) plugin instead.

### iOS

No additional setup is required. The plugin injects the home indicator override into the Capacitor bridge view controller automatically, so you do not need to subclass `CAPBridgeViewController` or edit your `AppDelegate`.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to hide and show the home indicator and check its current state.

### Hide and show the home indicator

Hide and show the home indicator at runtime. Note that calling `hide()` sets the home indicator to auto-hide: it only fades out while the screen is idle and reappears as soon as the user touches the screen. Only available on iOS:

```
import { HomeIndicator } from '@capawesome/capacitor-home-indicator';

const hide = async () => {
  await HomeIndicator.hide();
};

const show = async () => {
  await HomeIndicator.show();
};
```

### Check the current state

Check whether the home indicator is currently set to be hidden. This reflects the plugin-managed state, not the actual visibility on screen. Only available on iOS:

```
import { HomeIndicator } from '@capawesome/capacitor-home-indicator';

const isHidden = async () => {
  const { hidden } = await HomeIndicator.isHidden();
  return hidden;
};
```

## API

- [`hide()`](#hide)
- [`isHidden()`](#ishidden)
- [`show()`](#show)
- [Interfaces](#interfaces)

### hide()

```
hide() => Promise<void>
```

Hide the home indicator.

The home indicator auto-hides while the screen is idle and reappears when the user touches the screen. The system does not allow permanently removing the home indicator.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### isHidden()

```
isHidden() => Promise<IsHiddenResult>
```

Check whether the home indicator is currently set to be hidden.

This reflects the plugin-managed state, not the actual visibility of the home indicator on screen (which the system controls). The state is kept in memory only and resets when the app is restarted.

Only available on iOS.

**Returns:** `Promise<IsHiddenResult>`

**Since:** 0.1.0

______________________________________________________________________

### show()

```
show() => Promise<void>
```

Show the home indicator.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IsHiddenResult

| Prop         | Type      | Description                                               | Since |
| ------------ | --------- | --------------------------------------------------------- | ----- |
| **`hidden`** | `boolean` | Whether the home indicator is currently set to be hidden. | 0.1.0 |

## Home Indicator Behavior

It is important to understand how the iOS home indicator behaves, as the operating system does not allow it to be permanently removed:

- **Auto-hide only**: Calling `hide()` sets the home indicator to auto-hide. The indicator only fades out while the screen is idle.
- **Reappears on touch**: As soon as the user touches the screen, the home indicator reappears. It fades out again once the screen becomes idle. This is a system behavior enforced by iOS and cannot be changed.
- **In-memory state**: The state managed by this plugin is kept in memory only. It resets to shown when the app is restarted, so call `hide()` again after your app relaunches if needed.

## FAQ

### How is this plugin different from other similar plugins?

It focuses on doing one thing well: hiding and showing the iOS home indicator at runtime with zero native setup, injecting the override into the Capacitor bridge view controller automatically so you never subclass `CAPBridgeViewController` or edit your `AppDelegate`. The API is fully typed, ships for both CocoaPods and Swift Package Manager, and is kept current with the latest Capacitor and iOS releases. If all you need is to toggle the home indicator, this is a focused, drop-in solution.

### Why is the home indicator still visible after calling the hide method?

Calling `hide()` only sets the home indicator to auto-hide. The indicator fades out while the screen is idle and reappears as soon as the user touches the screen. This is a system behavior enforced by iOS and cannot be changed, since the operating system does not allow the home indicator to be permanently removed.

### Does this plugin work on Android or the Web?

No, the plugin is only available on iOS. On Android and Web, all methods reject as unimplemented. If you want to control the navigation bar on Android, use the [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/) plugin instead.

### Do I need to modify my native iOS project?

No, the plugin injects the home indicator override into the Capacitor bridge view controller automatically. You do not need to subclass `CAPBridgeViewController` or edit your `AppDelegate`.

### Is the hidden state persisted across app restarts?

No, the state managed by the plugin is kept in memory only and resets to shown when the app is restarted. If your app should always hide the home indicator, call `hide()` again after your app relaunches.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Edge-to-Edge Support](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/): Support edge-to-edge display on Android with features like setting the status bar and navigation bar color.
- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/): Set the background color and button style of the Android navigation bar.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/home-indicator/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/home-indicator/LICENSE).

# Capacitor In-App Browser Plugin

Capacitor plugin to open URLs in the external browser, the system browser or an embedded web view.

## Features

The Capacitor In-App Browser plugin is one of the most complete in-app browsing solutions for Capacitor apps. Here are some of the key features:

- 🌐 **Three browser modes**: Open URLs in the external browser, the system browser (Custom Tabs on Android, `SFSafariViewController` on iOS) or an embedded web view.
- 🧭 **Navigation events**: Get notified when the browser is closed, a page has been loaded or a navigation has been completed.
- 💉 **JavaScript execution**: Execute any JavaScript code in the embedded web view.
- 💬 **Messaging**: Exchange messages between your app and the web page in both directions.
- 🎨 **Toolbar theming**: Customize the toolbar color, title, close button and navigation buttons.
- 🍪 **Session control**: Clear the cache and cookies, or use an isolated data store on iOS.
- 🎥 **Media permissions**: Camera and microphone permission requests from web pages are forwarded to the app.
- 🤝 **Compatibility**: Works alongside the [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/), [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/) and [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The In-App Browser plugin is typically used whenever an app needs to display web content without losing the user, for example:

- **External links**: Open links, terms of service, or documentation in the system browser without leaving the app context.
- **Login and checkout flows**: Open a web-based flow in the embedded web view and watch for a redirect using the `browserUrlChanged` event.
- **Hybrid web content**: Embed a web page with a themed native toolbar and exchange messages between the app and the page.
- **Background loading**: Load a URL in a hidden web view with the `visible` option and present it once the page has loaded.
- **Session control**: Clear the cache and cookies of the web view, or use an isolated data store on iOS.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| iOS |
| --- |
|     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-in-app-browser` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-in-app-browser
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$androidxBrowserVersion` version of `androidx.browser:browser` (default: `1.9.0`)

#### Permissions

If web pages opened in the embedded web view should be able to access the camera or microphone, the following elements must be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if web pages should be able to access the camera. -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- Required if web pages should be able to access the microphone. -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

The permissions must also be granted before a web page requests access to the camera or microphone.

### iOS

#### Privacy Descriptions

If web pages opened in the embedded web view should be able to access the camera or microphone, the `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` keys must be added to the `Info.plist` file of your app:

```
<key>NSCameraUsageDescription</key>
<string>The camera is used by websites opened in the in-app browser.</string>
<key>NSMicrophoneUsageDescription</key>
<string>The microphone is used by websites opened in the in-app browser.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to open URLs in the external, system, and in-app browsers, control the embedded web view, exchange messages with the loaded page, clear browsing data, and listen for browser events.

### Open a URL in the external browser

Open a URL in the default browser app of the device. Since the browser is opened in a separate app, no events are emitted in this mode:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInExternalBrowser = async () => {
  await InAppBrowser.openInExternalBrowser({
    url: 'https://capawesome.io',
  });
};
```

### Open a URL in the system browser

Open a URL in the system browser (Custom Tabs on Android, `SFSafariViewController` on iOS) and customize the toolbar with platform-specific options. Only available on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInSystemBrowser = async () => {
  await InAppBrowser.openInSystemBrowser({
    url: 'https://capawesome.io',
    android: {
      showTitle: true,
      toolbarColor: '#008080',
    },
    ios: {
      dismissButtonStyle: 'close',
      toolbarColor: '#008080',
    },
  });
};
```

### Open a URL in an embedded web view

Open a URL in an embedded web view with a native toolbar whose color, title, and buttons can be customized. Only available on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const openInWebView = async () => {
  await InAppBrowser.openInWebView({
    url: 'https://capawesome.io',
    toolbar: {
      backgroundColor: '#008080',
      color: '#FFFFFF',
      showNavigationButtons: true,
    },
  });
};
```

### Close the browser

Close the currently open browser. This closes browsers opened with `openInWebView(...)` or `openInSystemBrowser(...)`. Only available on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const close = async () => {
  await InAppBrowser.close();
};
```

### Execute JavaScript in the web view

Execute any JavaScript code in the currently open web view. This method is only available for browsers opened with `openInWebView(...)` on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const executeScript = async () => {
  const { result } = await InAppBrowser.executeScript({
    script: 'document.title',
  });
  return result;
};
```

### Post a message to the web page

Post a message to the currently open web view. The web page receives the message by listening for the `capacitorInAppBrowserMessage` window event, see [Messaging](#messaging). This method is only available for browsers opened with `openInWebView(...)` on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const postMessage = async () => {
  await InAppBrowser.postMessage({
    data: { name: 'Capawesome' },
  });
};
```

### Clear the cache and cookies

Clear the cache or the cookies of the web view, either for all URLs or only for a specific URL. Only available on Android and iOS:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const clearCache = async () => {
  await InAppBrowser.clearCache();
};

const clearAllCookies = async () => {
  await InAppBrowser.clearCookies();
};

const clearCookiesForUrl = async () => {
  await InAppBrowser.clearCookies({ url: 'https://capawesome.io' });
};
```

### Listen for browser events

Get notified when the browser is closed, a message is received, a navigation has been completed, a page has been loaded, or the URL has changed:

```
import { InAppBrowser } from '@capawesome/capacitor-in-app-browser';

const addListeners = async () => {
  await InAppBrowser.addListener('browserClosed', () => {
    console.log('Browser closed');
  });
  await InAppBrowser.addListener('browserMessageReceived', event => {
    console.log('Message received', event.data);
  });
  await InAppBrowser.addListener('browserNavigationCompleted', event => {
    console.log('Navigation completed', event.url);
  });
  await InAppBrowser.addListener('browserPageLoaded', () => {
    console.log('Browser page loaded');
  });
  await InAppBrowser.addListener('browserUrlChanged', event => {
    console.log('URL changed', event.url);
  });
};
```

## API

- [`clearCache()`](#clearcache)
- [`clearCookies(...)`](#clearcookies)
- [`close()`](#close)
- [`executeScript(...)`](#executescript)
- [`getCookies(...)`](#getcookies)
- [`openInExternalBrowser(...)`](#openinexternalbrowser)
- [`openInSystemBrowser(...)`](#openinsystembrowser)
- [`openInWebView(...)`](#openinwebview)
- [`postMessage(...)`](#postmessage)
- [`show()`](#show)
- [`addListener('browserClosed', ...)`](#addlistenerbrowserclosed-)
- [`addListener('browserMessageReceived', ...)`](#addlistenerbrowsermessagereceived-)
- [`addListener('browserNavigationCompleted', ...)`](#addlistenerbrowsernavigationcompleted-)
- [`addListener('browserPageLoaded', ...)`](#addlistenerbrowserpageloaded-)
- [`addListener('browserUrlChanged', ...)`](#addlistenerbrowserurlchanged-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### clearCache()

```
clearCache() => Promise<void>
```

Clear the cache of the web view.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### clearCookies(...)

```
clearCookies(options?: ClearCookiesOptions | undefined) => Promise<void>
```

Clear the cookies of the web view.

Provide the `url` option to clear only the cookies of a specific URL. Otherwise, all cookies are cleared.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ClearCookiesOptions` |

**Since:** 0.2.0

______________________________________________________________________

### close()

```
close() => Promise<void>
```

Close the currently open browser.

This closes browsers opened with `openInWebView(...)` or `openInSystemBrowser(...)`.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### executeScript(...)

```
executeScript(options: ExecuteScriptOptions) => Promise<ExecuteScriptResult>
```

Execute a JavaScript script in the currently open web view.

This method is only available for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `ExecuteScriptOptions` |

**Returns:** `Promise<ExecuteScriptResult>`

**Since:** 0.1.0

______________________________________________________________________

### getCookies(...)

```
getCookies(options: GetCookiesOptions) => Promise<GetCookiesResult>
```

Get the cookies for a specific URL.

On iOS, only cookies from the shared data store are returned. Cookies from a web view opened with `dataStore: 'isolated'` are not included.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `GetCookiesOptions` |

**Returns:** `Promise<GetCookiesResult>`

**Since:** 0.1.0

______________________________________________________________________

### openInExternalBrowser(...)

```
openInExternalBrowser(options: OpenInExternalBrowserOptions) => Promise<void>
```

Open a URL in the default browser app of the device.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `OpenInExternalBrowserOptions` |

**Since:** 0.1.0

______________________________________________________________________

### openInSystemBrowser(...)

```
openInSystemBrowser(options: OpenInSystemBrowserOptions) => Promise<void>
```

Open a URL in the system browser (Custom Tabs on Android, `SFSafariViewController` on iOS).

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `OpenInSystemBrowserOptions` |

**Since:** 0.1.0

______________________________________________________________________

### openInWebView(...)

```
openInWebView(options: OpenInWebViewOptions) => Promise<void>
```

Open a URL in an embedded web view with a native toolbar.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `OpenInWebViewOptions` |

**Since:** 0.1.0

______________________________________________________________________

### postMessage(...)

```
postMessage(options: PostMessageOptions) => Promise<void>
```

Post a message to the currently open web view.

The web page receives the message by listening for the `capacitorInAppBrowserMessage` window event. The message data is available in the `detail` property of the event.

This method is only available for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `PostMessageOptions` |

**Since:** 0.1.0

______________________________________________________________________

### show()

```
show() => Promise<void>
```

Show the web view if it was opened with `visible: false`.

This method is only available for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('browserClosed', ...)

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

Called when the browser is closed.

Only available on Android and iOS.

| Param              | Type              |
| ------------------ | ----------------- |
| **`eventName`**    | `'browserClosed'` |
| **`listenerFunc`** | `() => void`      |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('browserMessageReceived', ...)

```
addListener(eventName: 'browserMessageReceived', listenerFunc: (event: BrowserMessageReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the web page posts a message to the app using the injected `window.CapacitorInAppBrowser.postMessage(...)` function.

This event is only emitted for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param              | Type                                           |
| ------------------ | ---------------------------------------------- |
| **`eventName`**    | `'browserMessageReceived'`                     |
| **`listenerFunc`** | `(event: BrowserMessageReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('browserNavigationCompleted', ...)

```
addListener(eventName: 'browserNavigationCompleted', listenerFunc: (event: BrowserNavigationCompletedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a page navigation has been completed in the web view.

This event is only emitted for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param              | Type                                               |
| ------------------ | -------------------------------------------------- |
| **`eventName`**    | `'browserNavigationCompleted'`                     |
| **`listenerFunc`** | `(event: BrowserNavigationCompletedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('browserPageLoaded', ...)

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

Called when the initial page of the browser has finished loading.

On Android, this event is only emitted for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param              | Type                  |
| ------------------ | --------------------- |
| **`eventName`**    | `'browserPageLoaded'` |
| **`listenerFunc`** | `() => void`          |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('browserUrlChanged', ...)

```
addListener(eventName: 'browserUrlChanged', listenerFunc: (event: BrowserUrlChangedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the current URL of the web view changes, e.g. when the user navigates to a new page, a server redirect occurs, or a single-page application updates the browser history.

This event is also emitted for the initial URL and fires earlier than `browserNavigationCompleted`.

This event is only emitted for browsers opened with `openInWebView(...)`.

Only available on Android and iOS.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'browserUrlChanged'`                     |
| **`listenerFunc`** | `(event: BrowserUrlChangedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ClearCookiesOptions

| Prop      | Type     | Description                                                                 | Since |
| --------- | -------- | --------------------------------------------------------------------------- | ----- |
| **`url`** | `string` | The URL to clear the cookies for. If not provided, all cookies are cleared. | 0.2.0 |

#### ExecuteScriptResult

| Prop         | Type     | Description | Since                                                                                                                                        |
| ------------ | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **`result`** | \`string | null\`      | The result of the script execution serialized as a JSON string. If the script does not return a JSON-serializable value, `null` is returned. |

#### ExecuteScriptOptions

| Prop         | Type     | Description                                     | Since |
| ------------ | -------- | ----------------------------------------------- | ----- |
| **`script`** | `string` | The JavaScript code to execute in the web view. | 0.1.0 |

#### GetCookiesResult

| Prop          | Type                         | Description                                                 | Since |
| ------------- | ---------------------------- | ----------------------------------------------------------- | ----- |
| **`cookies`** | `{ [key: string]: string; }` | The cookies for the URL as a map of cookie names to values. | 0.1.0 |

#### GetCookiesOptions

| Prop      | Type     | Description                     | Since |
| --------- | -------- | ------------------------------- | ----- |
| **`url`** | `string` | The URL to get the cookies for. | 0.1.0 |

#### OpenInExternalBrowserOptions

| Prop      | Type     | Description                              | Since |
| --------- | -------- | ---------------------------------------- | ----- |
| **`url`** | `string` | The URL to open in the external browser. | 0.1.0 |

#### OpenInSystemBrowserOptions

| Prop          | Type                                | Description                                                          | Since |
| ------------- | ----------------------------------- | -------------------------------------------------------------------- | ----- |
| **`android`** | `OpenInSystemBrowserAndroidOptions` | Options that are only applied on Android. Only available on Android. | 0.1.0 |
| **`ios`**     | `OpenInSystemBrowserIosOptions`     | Options that are only applied on iOS. Only available on iOS.         | 0.1.0 |
| **`url`**     | `string`                            | The URL to open in the system browser.                               | 0.1.0 |

#### OpenInSystemBrowserAndroidOptions

| Prop                      | Type      | Description                                                                                                | Default | Since |
| ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`hideToolbarOnScroll`** | `boolean` | Whether or not the toolbar should be hidden when the user scrolls down and shown when the user scrolls up. | `false` | 0.1.0 |
| **`showTitle`**           | `boolean` | Whether or not the title of the web page should be shown in the toolbar.                                   | `false` | 0.1.0 |
| **`toolbarColor`**        | `string`  | The background color of the toolbar as a hex color code.                                                   |         | 0.1.0 |

#### OpenInSystemBrowserIosOptions

| Prop                     | Type                 | Description                                                                                             | Default  | Since |
| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------- | -------- | ----- |
| **`barCollapsing`**      | `boolean`            | Whether or not the toolbar should collapse when the user scrolls down.                                  | `true`   | 0.1.0 |
| **`dismissButtonStyle`** | `DismissButtonStyle` | The style of the dismiss button in the toolbar.                                                         | `'done'` | 0.1.0 |
| **`readerMode`**         | `boolean`            | Whether or not the reader mode should be entered if it is available for the web page.                   | `false`  | 0.1.0 |
| **`toolbarColor`**       | `string`             | The background color of the toolbar as a hex color code. This option has no effect on iOS 26 and later. |          | 0.1.0 |

#### OpenInWebViewOptions

| Prop                                  | Type                          | Description                                                                                                                                                                                                                                                        | Default    | Since |
| ------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----- |
| **`android`**                         | `OpenInWebViewAndroidOptions` | Options that are only applied on Android. Only available on Android.                                                                                                                                                                                               |            | 0.1.0 |
| **`dataStore`**                       | `WebViewDataStore`            | The data store to use for the web view. On Android, this option is ignored. The web view always uses the app-global (`shared`) data store. Only available on iOS.                                                                                                  | `'shared'` | 0.1.0 |
| **`headers`**                         | `{ [key: string]: string; }`  | Additional HTTP headers to send with the initial request.                                                                                                                                                                                                          |            | 0.1.0 |
| **`ios`**                             | `OpenInWebViewIosOptions`     | Options that are only applied on iOS. Only available on iOS.                                                                                                                                                                                                       |            | 0.1.0 |
| **`mediaPlaybackRequiresUserAction`** | `boolean`                     | Whether or not media playback requires user action.                                                                                                                                                                                                                | `false`    | 0.1.0 |
| **`toolbar`**                         | `WebViewToolbarOptions`       | Options for the toolbar of the web view.                                                                                                                                                                                                                           |            | 0.1.0 |
| **`url`**                             | `string`                      | The URL to open in the web view.                                                                                                                                                                                                                                   |            | 0.1.0 |
| **`userAgent`**                       | `string`                      | The custom user agent to use for the web view.                                                                                                                                                                                                                     |            | 0.1.0 |
| **`visible`**                         | `boolean`                     | Whether or not the web view is presented when opened. If `false`, the web view loads the URL in the background and stays hidden until `show()` is called. The `browserPageLoaded` event is still emitted and `close()` can be called while the web view is hidden. | `true`     | 0.1.0 |

#### OpenInWebViewAndroidOptions

| Prop                       | Type      | Description                                                                                                                                                                         | Default | Since |
| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`allowZoom`**            | `boolean` | Whether or not the user can zoom the web page.                                                                                                                                      | `false` | 0.1.0 |
| **`hardwareBackButton`**   | `boolean` | Whether or not the hardware back button navigates back in the web view's history before closing the web view. If `false`, the hardware back button closes the web view immediately. | `true`  | 0.1.0 |
| **`pauseMediaWhenHidden`** | `boolean` | Whether or not media playback is paused when the app is hidden.                                                                                                                     | `true`  | 0.1.0 |

#### OpenInWebViewIosOptions

| Prop                                      | Type      | Description                                                                                   | Default | Since |
| ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------- | ------- | ----- |
| **`allowsBackForwardNavigationGestures`** | `boolean` | Whether or not horizontal swipe gestures navigate back and forward in the web view's history. | `false` | 0.1.0 |
| **`overscroll`**                          | `boolean` | Whether or not the web view bounces when scrolled past the edge of the content.               | `true`  | 0.1.0 |

#### WebViewToolbarOptions

| Prop                        | Type      | Description                                                                                                                                  | Default   | Since |
| --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----- |
| **`backgroundColor`**       | `string`  | The background color of the toolbar as a hex color code. On iOS 26 and later, this replaces the Liquid Glass toolbar with an opaque toolbar. |           | 0.1.0 |
| **`closeButtonText`**       | `string`  | The text of the close button in the toolbar.                                                                                                 | `'Close'` | 0.1.0 |
| **`color`**                 | `string`  | The text color of the toolbar as a hex color code.                                                                                           |           | 0.1.0 |
| **`showNavigationButtons`** | `boolean` | Whether or not the back and forward navigation buttons should be shown in the toolbar.                                                       | `false`   | 0.1.0 |
| **`showUrl`**               | `boolean` | Whether or not the current URL should be displayed in the toolbar instead of the title.                                                      | `false`   | 0.1.0 |
| **`title`**                 | `string`  | The fixed title to display in the toolbar. If not set, the title of the current web page is displayed.                                       |           | 0.1.0 |
| **`visible`**               | `boolean` | Whether or not the toolbar should be visible.                                                                                                | `true`    | 0.1.0 |

#### PostMessageOptions

| Prop       | Type                          | Description                                                                   | Since |
| ---------- | ----------------------------- | ----------------------------------------------------------------------------- | ----- |
| **`data`** | `{ [key: string]: unknown; }` | The message data to post to the web view. Must be a JSON-serializable object. | 0.1.0 |

#### PluginListenerHandle

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

#### BrowserMessageReceivedEvent

| Prop       | Type      | Description                              | Since |
| ---------- | --------- | ---------------------------------------- | ----- |
| **`data`** | `unknown` | The message data posted by the web page. | 0.1.0 |

#### BrowserNavigationCompletedEvent

| Prop      | Type     | Description                                | Since |
| --------- | -------- | ------------------------------------------ | ----- |
| **`url`** | `string` | The URL of the page that was navigated to. | 0.1.0 |

#### BrowserUrlChangedEvent

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`url`** | `string` | The new URL of the web view. | 0.1.0 |

### Type Aliases

#### DismissButtonStyle

The style of the dismiss button in the toolbar of the system browser.

- `cancel`: A button with the text "Cancel".
- `close`: A button with the text "Close".
- `done`: A button with the text "Done".

`'cancel' | 'close' | 'done'`

#### WebViewDataStore

The data store to use for the web view.

- `isolated`: The web view uses a non-persistent data store. Cookies and web storage are discarded when the web view is closed.
- `shared`: The web view uses the app-global data store which is shared with other web views.

`'isolated' | 'shared'`

## Messaging

The embedded web view injects a small message bridge into every web page. This allows you to exchange messages between your app and the web page in both directions.

### From the web page to the app

The web page can post a message to the app using the injected `window.CapacitorInAppBrowser.postMessage(...)` function:

```
window.CapacitorInAppBrowser.postMessage({ name: 'Capawesome' });
```

The app receives the message via the `browserMessageReceived` event.

### From the app to the web page

The app can post a message to the web page using the `postMessage(...)` method. The web page receives the message by listening for the `capacitorInAppBrowserMessage` window event:

```
window.addEventListener('capacitorInAppBrowserMessage', event => {
  console.log('Message received', event.detail);
});
```

## Platform Behavior

The three browser modes behave differently on each platform. Keep the following differences in mind:

- **System browser**: Tracking the visited URLs is not possible by design. If you need the `browserNavigationCompleted` or `browserUrlChanged` event, use the `openInWebView(...)` method instead. On Android, the `browserPageLoaded` event is not emitted for the system browser and the `browserClosed` event is emitted when the user returns to the app.
- **Embedded web view**: The web view always uses the app-global (`shared`) data store on Android. The `dataStore` option is only supported on iOS. On iOS, hiding the toolbar removes the close button, so the browser can then only be closed using the `close(...)` method.
- **External browser**: The browser is opened in a separate app. For this reason, no events are emitted and the `close(...)` method has no effect.

## FAQ

### How is this plugin different from other similar plugins?

It covers three browsing modes in one fully typed API — the external browser, the system browser (Custom Tabs on Android, `SFSafariViewController` on iOS), and an embedded web view with a themed native toolbar, JavaScript execution, two-way messaging, navigation events, and session control. Camera and microphone requests from web pages are forwarded to the app, and you can even load a URL hidden in the background and present it once it's ready. If you only need to open a link, the external mode is a simple one-liner; if you need to embed, theme, and communicate with web content, this plugin is designed for exactly that.

### What is the difference between the external browser, the system browser and the embedded web view?

The `openInExternalBrowser(...)` method opens the URL in the default browser app of the device, so no events are emitted and the `close()` method has no effect. The `openInSystemBrowser(...)` method presents the system browser (Custom Tabs on Android, `SFSafariViewController` on iOS) inside your app with a customizable toolbar. The `openInWebView(...)` method opens an embedded web view with a native toolbar and offers the most control, including JavaScript execution, messaging, and navigation events. See [Platform Behavior](#platform-behavior) for the differences between the modes.

### How can I track which URLs the user visits?

Tracking the visited URLs is only possible in the embedded web view. Open the URL with `openInWebView(...)` and listen for the `browserUrlChanged` or `browserNavigationCompleted` event. In the system browser, tracking the visited URLs is not possible by design, and in the external browser no events are emitted at all.

### How can I exchange data between my app and the opened web page?

The embedded web view injects a small message bridge into every web page. The web page can post messages to the app using the injected `window.CapacitorInAppBrowser.postMessage(...)` function, which the app receives via the `browserMessageReceived` event. The app can post messages to the web page using the `postMessage(...)` method, which the web page receives via the `capacitorInAppBrowserMessage` window event. See [Messaging](#messaging) for more details.

### Can web pages access the camera or microphone?

Yes, camera and microphone permission requests from web pages opened in the embedded web view are forwarded to the app. On Android, the corresponding permissions must be declared in your `AndroidManifest.xml` and granted before a web page requests access. On iOS, the `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` keys must be added to your `Info.plist` file. See [Installation](#installation) for details.

### Can I load a URL in the background before showing it?

Yes, open the URL with `openInWebView(...)` and set the `visible` option to `false`. The web view then loads the URL in the background and stays hidden until you call the `show()` method. The `browserPageLoaded` event is still emitted and `close()` can be called while the web view is hidden.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/): Check if an app can be opened and open it.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers.
- [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/): Detect an outdated Android System WebView and guide users to update it.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/in-app-browser/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/in-app-browser/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/in-app-browser/LICENSE).

# Capacitor Install Referrer Plugin

Capacitor plugin for reading install attribution data from the [Play Install Referrer](https://developer.android.com/google/play/installreferrer) and [Apple Ad Services](https://developer.apple.com/documentation/adservices).

## Features

- 🤖 **Play Install Referrer**: Read the Play Store install referrer on Android.
- 🍏 **Apple Ad Services**: Read the Apple Ad Services attribution token on iOS.
- 🤝 **Compatibility**: Works alongside the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/), [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/) and [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Install Referrer plugin is typically used to attribute app installs to marketing campaigns, for example:

- **Campaign attribution**: Attribute Android installs to a campaign by reading the referrer URL of the installed package.
- **Apple Search Ads measurement**: Measure iOS campaign performance by exchanging the Apple Ad Services attribution token server-side.
- **Deferred deep linking**: Pass parameters through the Play Store referrer URL to route users to the right content after the first launch.
- **Google Play Instant detection**: Detect whether the app was installed via a Google Play Instant experience within the past 7 days.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-install-referrer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-install-referrer
npx cap sync
```

The `getInstallReferrer(...)` method is only available on **Android**, the `getAttributionToken(...)` method is only available on **iOS**. On all other platforms, the respective method rejects as unimplemented.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$installReferrerVersion` version of `com.android.installreferrer:installreferrer` (default: `2.2`)

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read the Play Store install referrer on Android and the Apple Ad Services attribution token on iOS.

### Read the Play Store install referrer

Get the Play Store install referrer information, including the referrer URL and the click and install timestamps. Fetch it once shortly after the first launch and persist it, since Google only guarantees its availability for a limited window after the install. Only available on Android:

```
import { InstallReferrer } from '@capawesome/capacitor-install-referrer';

const getInstallReferrer = async () => {
  const result = await InstallReferrer.getInstallReferrer();
  return result;
};
```

### Read the Apple Ad Services attribution token

Get the Apple Ad Services attribution token. The token is opaque and must be exchanged server-side with Apple's attribution API (see [Attribution Token Exchange](#attribution-token-exchange-ios)). Only available on iOS:

```
import { InstallReferrer } from '@capawesome/capacitor-install-referrer';

const getAttributionToken = async () => {
  const { token } = await InstallReferrer.getAttributionToken();
  return token;
};
```

## API

- [`getAttributionToken()`](#getattributiontoken)
- [`getInstallReferrer()`](#getinstallreferrer)
- [Interfaces](#interfaces)

### getAttributionToken()

```
getAttributionToken() => Promise<GetAttributionTokenResult>
```

Get the Apple Ad Services attribution token.

The token is opaque and only the client half of the attribution flow. It must be exchanged server-side with Apple's Ad Services attribution API (`https://api-adservices.apple.com/api/v1/`) and expires after 24 hours.

Only available on iOS.

**Returns:** `Promise<GetAttributionTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### getInstallReferrer()

```
getInstallReferrer() => Promise<GetInstallReferrerResult>
```

Get the Play Store install referrer information.

The referrer should be fetched once shortly after the first launch and persisted by your app. Google only guarantees availability for a limited window after the install.

Only available on Android.

**Returns:** `Promise<GetInstallReferrerResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetAttributionTokenResult

| Prop        | Type     | Description                              | Since |
| ----------- | -------- | ---------------------------------------- | ----- |
| **`token`** | `string` | The Apple Ad Services attribution token. | 0.1.0 |

#### GetInstallReferrerResult

| Prop                               | Type      | Description                                                                                | Since |
| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------ | ----- |
| **`googlePlayInstantParam`**       | `boolean` | Whether the app was installed via a Google Play Instant experience within the past 7 days. | 0.1.0 |
| **`installBeginTimestampMillis`**  | `number`  | The client-side timestamp (in milliseconds) when the app installation began.               | 0.1.0 |
| **`referrerClickTimestampMillis`** | `number`  | The client-side timestamp (in milliseconds) when the referrer click happened.              | 0.1.0 |
| **`referrerUrl`**                  | `string`  | The referrer URL of the installed package.                                                 | 0.1.0 |

## Install Referrer Window (Android)

Google only guarantees that the Play Store install referrer is available for a limited window after the app is installed. You should fetch the referrer once shortly after the first launch and persist it in your app, so that it remains available later.

## Attribution Token Exchange (iOS)

The token returned by `getAttributionToken(...)` is opaque and only the client half of the attribution flow. To resolve the attribution data, you must exchange the token server-side against Apple's Ad Services attribution API:

```
POST https://api-adservices.apple.com/api/v1/
Content-Type: text/plain

<attribution-token>
```

The token expires after 24 hours, so it should be exchanged promptly. See the [Apple documentation](<https://developer.apple.com/documentation/adservices/aaattribution/attributiontoken()>) for more information.

## FAQ

### How is this plugin different from other similar plugins?

It brings the Android Play Install Referrer and the iOS Apple Ad Services attribution token together under one fully typed API, so a single dependency covers install attribution across both platforms. It surfaces the complete referrer details — referrer URL, click and install timestamps, and Google Play Instant detection — and documents the Android availability window and the server-side Apple token exchange clearly. It's actively maintained against the latest Capacitor and OS versions, so campaign attribution and deferred deep linking stay reliable as the platforms evolve.

### Which platforms does this plugin support?

The `getInstallReferrer(...)` method is only available on Android and the `getAttributionToken(...)` method is only available on iOS. On all other platforms, the respective method rejects as unimplemented.

### Why is the install referrer no longer available on Android?

Google only guarantees that the Play Store install referrer is available for a limited window after the app is installed. You should therefore fetch the referrer once shortly after the first launch and persist it in your app, so that it remains available later.

### How do I resolve the attribution data from the Apple attribution token?

The token returned by `getAttributionToken(...)` is opaque and only the client half of the attribution flow. You must exchange it server-side against Apple's Ad Services attribution API, as described in [Attribution Token Exchange](#attribution-token-exchange-ios). Note that the token expires after 24 hours, so it should be exchanged promptly.

### Do I need any permissions or special configuration?

No, the plugin does not require any runtime permissions or configuration. On Android, it uses the `com.android.installreferrer:installreferrer` library, whose version can be changed via the `$installReferrerVersion` project variable if needed (see [Installation](#installation)).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the user's permission to track them via the App Tracking Transparency framework on iOS.
- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Measure user engagement with Firebase Analytics.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Capture analytics events with the PostHog platform.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/install-referrer/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/install-referrer/LICENSE).

# Capacitor Intercom Plugin

Unofficial Capacitor plugin for [Intercom](https://www.intercom.com/).[1](#fn:1)

## Features

The Capacitor Intercom plugin is a modern integration of the Intercom SDKs for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 💬 **Messenger**: Present the Intercom Messenger and its Home, Messages, Help Center, and Tickets spaces.
- 👤 **Identity**: Log in identified or unidentified users with the modern login APIs, wired to the native result callbacks.
- 🔐 **Identity Verification**: Verify the user's identity with a user hash (HMAC) or a JSON Web Token (JWT).
- 🧩 **User Attributes**: Update the user's name, email, phone, custom attributes, and companies.
- 📚 **Content**: Present articles, carousels, surveys, conversations, and help center collections.
- 🔢 **Unread Count**: Read the unread conversation count and listen for changes.
- 🔔 **Push Notifications**: Compose cleanly with Firebase Cloud Messaging (Android) and APNs (iOS).
- 🌐 **Typed Web SDK**: Uses the official `@intercom/messenger-js-sdk` package on the web.
- 🤝 **Compatibility**: Looking for a different chat SDK? Check out the [Crisp](https://capawesome.io/docs/sdks/capacitor/crisp/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Intercom plugin is typically used wherever you want to offer live chat and customer support inside your app, for example:

- **Customer support**: Let users chat with your support team directly from within the app.
- **User identification**: Attach the signed-in user's identity and attributes to every conversation.
- **Self-service**: Point users to articles, surveys, and help center collections without leaving the app.
- **Engagement**: Track events and show the unread conversation count in your own UI.
- **Re-engagement**: Notify users about new replies via push notifications.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-intercom` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-intercom @intercom/messenger-js-sdk
npx cap sync
```

This plugin requires an [Intercom](https://www.intercom.com/) account. You can find your **App ID** and the platform-specific **API keys** in the Intercom dashboard under **Settings → Installation**.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$intercomSdkVersion` version of `io.intercom.android:intercom-sdk-base` (default: `18.4.0`)

This plugin depends on `intercom-sdk-base` (not the full `intercom-sdk` artifact) on purpose. The full artifact ships its own `FirebaseMessagingService` and automatically integrates Firebase Cloud Messaging, which conflicts with apps that manage push notifications themselves (e.g. via [`@capacitor-firebase/messaging`](https://github.com/capawesome-team/capacitor-firebase)). The base artifact leaves push handling to you (see below).

#### Push Notifications

Push notifications on Android are delivered through [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging). Because this plugin uses the base SDK, you forward the push token and incoming messages to Intercom from your JavaScript code. This is what makes the plugin coexist cleanly with [`@capacitor-firebase/messaging`](https://github.com/capawesome-team/capacitor-firebase):

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';
import { Intercom } from '@capawesome/capacitor-intercom';

// Forward the FCM token to Intercom.
FirebaseMessaging.addListener('tokenReceived', async ({ token }) => {
  await Intercom.sendPushTokenToIntercom({ token });
});

// Forward incoming messages to Intercom.
FirebaseMessaging.addListener('notificationReceived', async ({ notification }) => {
  const data = notification.data ?? {};
  const { intercom } = await Intercom.isIntercomPushNotification({ data });
  if (intercom) {
    await Intercom.handlePushNotification({ data });
  }
});
```

### iOS

The Intercom iOS SDK can be integrated via Swift Package Manager (recommended) or CocoaPods.

#### Info.plist

To manage push notifications yourself (and coexist with other push plugins), disable Intercom's automatic push integration by adding the following key to your `ios/App/App/Info.plist` file:

```
<key>IntercomAutoIntegratePushNotifications</key>
<false/>
```

#### Push Notifications

Push notifications on iOS are delivered through [Apple Push Notification service (APNs)](https://developer.apple.com/documentation/usernotifications):

1. Enable the **Push Notifications** capability for your app target in Xcode.
1. Register for remote notifications (e.g. via [`@capacitor-firebase/messaging`](https://github.com/capawesome-team/capacitor-firebase) or `@capacitor/push-notifications`).
1. Forward the APNs device token to Intercom as a hexadecimal string:

```
import { PushNotifications } from '@capacitor/push-notifications';
import { Intercom } from '@capawesome/capacitor-intercom';

PushNotifications.addListener('registration', async ({ value }) => {
  // `value` is the hexadecimal APNs device token on iOS.
  await Intercom.sendPushTokenToIntercom({ token: value });
});
```

You can then check and handle incoming notifications the same way as on Android using `isIntercomPushNotification(...)` and `handlePushNotification(...)`.

### Web

The web implementation loads the Intercom Messenger from Intercom's CDN at runtime. This requires an active network connection. If your app enforces a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), make sure to allow the Intercom domains (e.g. `https://widget.intercom.io`, `https://js.intercomcdn.com`, and `wss://*.intercom.io`).

> [!NOTE] On the web, the Intercom launcher is visible by default after `initialize(...)`, whereas on Android and iOS it is hidden until you present the Messenger. Use `setLauncherVisible({ visible: false })` on the web if you want to match the mobile behavior.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Initialize the plugin

Call `initialize(...)` once before all other methods:

```
import { Intercom } from '@capawesome/capacitor-intercom';

const initialize = async () => {
  await Intercom.initialize({
    appId: 'YOUR_APP_ID',
    androidApiKey: 'YOUR_ANDROID_API_KEY',
    iosApiKey: 'YOUR_IOS_API_KEY',
  });
};
```

### Log in a user

Log in an identified user, optionally with identity verification:

```
import { Intercom } from '@capawesome/capacitor-intercom';

const loginUser = async () => {
  await Intercom.setUserHash({ userHash: 'YOUR_HMAC_HASH' });
  await Intercom.loginUser({
    userId: 'jane-doe',
    email: 'jane.doe@example.com',
  });
};
```

### Update the user

Update the attributes of the current user:

```
import { Intercom } from '@capawesome/capacitor-intercom';

const updateUser = async () => {
  await Intercom.updateUser({
    name: 'Jane Doe',
    customAttributes: { plan: 'pro' },
    companies: [{ id: 'capawesome', name: 'Capawesome', plan: 'enterprise' }],
  });
};
```

### Present the Messenger

Present the Intercom Messenger or a specific piece of content:

```
import { Intercom } from '@capawesome/capacitor-intercom';

const present = async () => {
  await Intercom.present({ space: 'home' });
};

const presentArticle = async () => {
  await Intercom.presentContent({ type: 'article', id: '123456' });
};
```

### Listen for events

Listen for the unread conversation count:

```
import { Intercom } from '@capawesome/capacitor-intercom';

const addListeners = async () => {
  await Intercom.addListener('unreadConversationCountChange', ({ count }) => {
    console.log('Unread conversations:', count);
  });
};
```

## API

- [`getUnreadConversationCount()`](#getunreadconversationcount)
- [`handlePushNotification(...)`](#handlepushnotification)
- [`hide()`](#hide)
- [`initialize(...)`](#initialize)
- [`isIntercomPushNotification(...)`](#isintercompushnotification)
- [`logEvent(...)`](#logevent)
- [`loginUnidentifiedUser()`](#loginunidentifieduser)
- [`loginUser(...)`](#loginuser)
- [`logout()`](#logout)
- [`present(...)`](#present)
- [`presentContent(...)`](#presentcontent)
- [`presentMessageComposer(...)`](#presentmessagecomposer)
- [`sendPushTokenToIntercom(...)`](#sendpushtokentointercom)
- [`setBottomPadding(...)`](#setbottompadding)
- [`setInAppMessagesVisible(...)`](#setinappmessagesvisible)
- [`setLauncherVisible(...)`](#setlaunchervisible)
- [`setUserHash(...)`](#setuserhash)
- [`setUserJwt(...)`](#setuserjwt)
- [`updateUser(...)`](#updateuser)
- [`addListener('messengerHidden', ...)`](#addlistenermessengerhidden-)
- [`addListener('messengerShown', ...)`](#addlistenermessengershown-)
- [`addListener('unreadConversationCountChange', ...)`](#addlistenerunreadconversationcountchange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getUnreadConversationCount()

```
getUnreadConversationCount() => Promise<GetUnreadConversationCountResult>
```

Get the number of unread conversations for the current user.

**Returns:** `Promise<GetUnreadConversationCountResult>`

**Since:** 0.1.0

______________________________________________________________________

### handlePushNotification(...)

```
handlePushNotification(options: HandlePushNotificationOptions) => Promise<void>
```

Handle an incoming push notification that belongs to Intercom.

Use `isIntercomPushNotification(...)` to check whether the notification belongs to Intercom before calling this method.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `HandlePushNotificationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### hide()

```
hide() => Promise<void>
```

Hide any currently presented Intercom UI (e.g. the Messenger).

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the Intercom SDK with your app ID and API key.

This method must be called before any other method.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isIntercomPushNotification(...)

```
isIntercomPushNotification(options: IsIntercomPushNotificationOptions) => Promise<IsIntercomPushNotificationResult>
```

Check whether an incoming push notification belongs to Intercom.

Only available on Android and iOS.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `IsIntercomPushNotificationOptions` |

**Returns:** `Promise<IsIntercomPushNotificationResult>`

**Since:** 0.1.0

______________________________________________________________________

### logEvent(...)

```
logEvent(options: LogEventOptions) => Promise<void>
```

Log an event with an optional set of metadata.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `LogEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### loginUnidentifiedUser()

```
loginUnidentifiedUser() => Promise<void>
```

Log in an unidentified (anonymous) user.

**Since:** 0.1.0

______________________________________________________________________

### loginUser(...)

```
loginUser(options: LoginUserOptions) => Promise<void>
```

Log in an identified user with a user ID and/or an email address.

At least one of `userId` or `email` must be provided.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `LoginUserOptions` |

**Since:** 0.1.0

______________________________________________________________________

### logout()

```
logout() => Promise<void>
```

Log out the current user and clear the local Intercom data.

**Since:** 0.1.0

______________________________________________________________________

### present(...)

```
present(options?: PresentOptions | undefined) => Promise<void>
```

Present the Intercom Messenger with the given space.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `PresentOptions` |

**Since:** 0.1.0

______________________________________________________________________

### presentContent(...)

```
presentContent(options: PresentContentOptions) => Promise<void>
```

Present a specific piece of Intercom content (e.g. an article, carousel, survey, or conversation).

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `PresentContentOptions` |

**Since:** 0.1.0

______________________________________________________________________

### presentMessageComposer(...)

```
presentMessageComposer(options?: PresentMessageComposerOptions | undefined) => Promise<void>
```

Present the Intercom message composer, optionally pre-filled with an initial message.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `PresentMessageComposerOptions` |

**Since:** 0.1.0

______________________________________________________________________

### sendPushTokenToIntercom(...)

```
sendPushTokenToIntercom(options: SendPushTokenToIntercomOptions) => Promise<void>
```

Forward a push notification token to Intercom.

On Android, pass the Firebase Cloud Messaging (FCM) token. On iOS, pass the hexadecimal APNs device token.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SendPushTokenToIntercomOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setBottomPadding(...)

```
setBottomPadding(options: SetBottomPaddingOptions) => Promise<void>
```

Set the bottom padding of the Intercom UI (in-app messages and launcher).

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetBottomPaddingOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setInAppMessagesVisible(...)

```
setInAppMessagesVisible(options: SetInAppMessagesVisibleOptions) => Promise<void>
```

Set whether in-app messages are visible.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SetInAppMessagesVisibleOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setLauncherVisible(...)

```
setLauncherVisible(options: SetLauncherVisibleOptions) => Promise<void>
```

Set whether the Intercom launcher is visible.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SetLauncherVisibleOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUserHash(...)

```
setUserHash(options: SetUserHashOptions) => Promise<void>
```

Set the user hash (HMAC) for identity verification.

This must be called before logging in the user.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetUserHashOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUserJwt(...)

```
setUserJwt(options: SetUserJwtOptions) => Promise<void>
```

Set the JSON Web Token (JWT) for identity verification.

This must be called before logging in the user.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetUserJwtOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updateUser(...)

```
updateUser(options: UpdateUserOptions) => Promise<void>
```

Update the attributes of the current user.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `UpdateUserOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('messengerHidden', ...)

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

Called when the Intercom Messenger is hidden.

Only available on iOS and Web.

| Param              | Type                |
| ------------------ | ------------------- |
| **`eventName`**    | `'messengerHidden'` |
| **`listenerFunc`** | `() => void`        |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('messengerShown', ...)

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

Called when the Intercom Messenger is shown.

Only available on iOS and Web.

| Param              | Type               |
| ------------------ | ------------------ |
| **`eventName`**    | `'messengerShown'` |
| **`listenerFunc`** | `() => void`       |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('unreadConversationCountChange', ...)

```
addListener(eventName: 'unreadConversationCountChange', listenerFunc: (event: UnreadConversationCountChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the number of unread conversations changes.

| Param              | Type                                                  |
| ------------------ | ----------------------------------------------------- |
| **`eventName`**    | `'unreadConversationCountChange'`                     |
| **`listenerFunc`** | `(event: UnreadConversationCountChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetUnreadConversationCountResult

| Prop        | Type     | Description                         | Since |
| ----------- | -------- | ----------------------------------- | ----- |
| **`count`** | `number` | The number of unread conversations. | 0.1.0 |

#### HandlePushNotificationOptions

| Prop       | Type                      | Description                        | Since |
| ---------- | ------------------------- | ---------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data of the push notification. | 0.1.0 |

#### InitializeOptions

| Prop                | Type     | Description                                                                      | Since |
| ------------------- | -------- | -------------------------------------------------------------------------------- | ----- |
| **`androidApiKey`** | `string` | The Android API key of your Intercom app. Required to use the plugin on Android. | 0.1.0 |
| **`appId`**         | `string` | The app ID of your Intercom app.                                                 | 0.1.0 |
| **`iosApiKey`**     | `string` | The iOS API key of your Intercom app. Required to use the plugin on iOS.         | 0.1.0 |

#### IsIntercomPushNotificationResult

| Prop           | Type      | Description                                        | Since |
| -------------- | --------- | -------------------------------------------------- | ----- |
| **`intercom`** | `boolean` | Whether the push notification belongs to Intercom. | 0.1.0 |

#### IsIntercomPushNotificationOptions

| Prop       | Type                      | Description                        | Since |
| ---------- | ------------------------- | ---------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data of the push notification. | 0.1.0 |

#### LogEventOptions

| Prop       | Type                     | Description            | Since      |
| ---------- | ------------------------ | ---------------------- | ---------- |
| **`data`** | \`Record\<string, string | number                 | boolean>\` |
| **`name`** | `string`                 | The name of the event. | 0.1.0      |

#### LoginUserOptions

| Prop         | Type     | Description                        | Since |
| ------------ | -------- | ---------------------------------- | ----- |
| **`email`**  | `string` | The email address of the user.     | 0.1.0 |
| **`userId`** | `string` | The unique identifier of the user. | 0.1.0 |

#### PresentOptions

| Prop        | Type            | Description           | Default  | Since |
| ----------- | --------------- | --------------------- | -------- | ----- |
| **`space`** | `IntercomSpace` | The space to present. | `'home'` | 0.1.0 |

#### PresentContentOptions

| Prop       | Type                  | Description                                                                                                                   | Since |
| ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**   | `string`              | The identifier of the content to present. Required for the `article`, `carousel`, `survey`, and `conversation` content types. | 0.1.0 |
| **`ids`**  | `string[]`            | The identifiers of the content to present. Required for the `help-center-collections` content type.                           | 0.1.0 |
| **`type`** | `IntercomContentType` | The type of content to present.                                                                                               | 0.1.0 |

#### PresentMessageComposerOptions

| Prop                 | Type     | Description                                | Since |
| -------------------- | -------- | ------------------------------------------ | ----- |
| **`initialMessage`** | `string` | The message to pre-fill the composer with. | 0.1.0 |

#### SendPushTokenToIntercomOptions

| Prop        | Type     | Description                                                                                                                                   | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`token`** | `string` | The push notification token. On Android, this is the Firebase Cloud Messaging (FCM) token. On iOS, this is the hexadecimal APNs device token. | 0.1.0 |

#### SetBottomPaddingOptions

| Prop          | Type     | Description                | Since |
| ------------- | -------- | -------------------------- | ----- |
| **`padding`** | `number` | The bottom padding to set. | 0.1.0 |

#### SetInAppMessagesVisibleOptions

| Prop          | Type      | Description                                | Since |
| ------------- | --------- | ------------------------------------------ | ----- |
| **`visible`** | `boolean` | Whether in-app messages should be visible. | 0.1.0 |

#### SetLauncherVisibleOptions

| Prop          | Type      | Description                             | Since |
| ------------- | --------- | --------------------------------------- | ----- |
| **`visible`** | `boolean` | Whether the launcher should be visible. | 0.1.0 |

#### SetUserHashOptions

| Prop           | Type     | Description                                                                                                                                                         | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`userHash`** | `string` | The user hash (HMAC) for identity verification. The hash must be generated on your backend using your Intercom secret key. Never expose the secret key in your app. | 0.1.0 |

#### SetUserJwtOptions

| Prop      | Type     | Description                                                                                                                                                              | Since |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`jwt`** | `string` | The JSON Web Token (JWT) for identity verification. The token must be generated on your backend using your Intercom secret key. Never expose the secret key in your app. | 0.1.0 |

#### UpdateUserOptions

| Prop                         | Type                     | Description                                                 | Since      |
| ---------------------------- | ------------------------ | ----------------------------------------------------------- | ---------- |
| **`companies`**              | `UpdateUserCompany[]`    | The companies the user belongs to.                          | 0.1.0      |
| **`customAttributes`**       | \`Record\<string, string | number                                                      | boolean>\` |
| **`email`**                  | `string`                 | The email address of the user.                              | 0.1.0      |
| **`languageOverride`**       | `string`                 | The preferred language of the user as an ISO 639-1 code.    | 0.1.0      |
| **`name`**                   | `string`                 | The name of the user.                                       | 0.1.0      |
| **`phone`**                  | `string`                 | The phone number of the user.                               | 0.1.0      |
| **`signedUpAt`**             | `number`                 | The date the user signed up as a Unix timestamp in seconds. | 0.1.0      |
| **`unsubscribedFromEmails`** | `boolean`                | Whether the user is unsubscribed from emails.               | 0.1.0      |
| **`userId`**                 | `string`                 | The unique identifier of the user.                          | 0.1.0      |

#### UpdateUserCompany

| Prop                   | Type                     | Description                                                      | Since      |
| ---------------------- | ------------------------ | ---------------------------------------------------------------- | ---------- |
| **`createdAt`**        | `number`                 | The date the company was created as a Unix timestamp in seconds. | 0.1.0      |
| **`customAttributes`** | \`Record\<string, string | number                                                           | boolean>\` |
| **`id`**               | `string`                 | The unique identifier of the company.                            | 0.1.0      |
| **`monthlySpend`**     | `number`                 | The monthly spend of the company.                                | 0.1.0      |
| **`name`**             | `string`                 | The name of the company.                                         | 0.1.0      |
| **`plan`**             | `string`                 | The plan of the company.                                         | 0.1.0      |

#### PluginListenerHandle

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

#### UnreadConversationCountChangeEvent

| Prop        | Type     | Description                         | Since |
| ----------- | -------- | ----------------------------------- | ----- |
| **`count`** | `number` | The number of unread conversations. | 0.1.0 |

### Type Aliases

#### IntercomSpace

A space of the Intercom Messenger.

`'home' | 'messages' | 'help-center' | 'tickets'`

#### IntercomContentType

A type of Intercom content that can be presented.

`'article' | 'carousel' | 'conversation' | 'help-center-collections' | 'survey'`

## Migration

If you are migrating from [`@capacitor-community/intercom`](https://github.com/capacitor-community/intercom) or another Intercom plugin, note that this plugin uses the **modern** Intercom API names throughout. The deprecated `register*` login methods are intentionally not exposed. The following table maps common legacy method names to their modern equivalents:

| Legacy method               | This plugin                         |
| --------------------------- | ----------------------------------- |
| `registerIdentifiedUser`    | `loginUser`                         |
| `registerUnidentifiedUser`  | `loginUnidentifiedUser`             |
| `logout`                    | `logout`                            |
| `displayMessenger`          | `present`                           |
| `displayMessageComposer`    | `presentMessageComposer`            |
| `displayArticle`            | `presentContent`                    |
| `displayCarousel`           | `presentContent`                    |
| `displayHelpCenter`         | `present({ space: 'help-center' })` |
| `hideMessenger`             | `hide`                              |
| `unreadConversationCount`   | `getUnreadConversationCount`        |
| `setLauncherVisibility`     | `setLauncherVisible`                |
| `setInAppMessageVisibility` | `setInAppMessagesVisible`           |
| `sendPushTokenToIntercom`   | `sendPushTokenToIntercom`           |

## Platform Support

Not every Intercom SDK feature is available on all platforms. The following table lists the notable per-platform differences of the plugin's API:

| Method / Event                                    | Android | iOS | Web |
| ------------------------------------------------- | ------- | --- | --- |
| `handlePushNotification(...)`                     | ✅      | ✅  | ❌  |
| `isIntercomPushNotification(...)`                 | ✅      | ✅  | ❌  |
| `presentContent(...)` (`carousel`)                | ✅      | ✅  | ❌  |
| `presentContent(...)` (`help-center-collections`) | ✅      | ✅  | ❌  |
| `sendPushTokenToIntercom(...)`                    | ✅      | ✅  | ❌  |
| `setBottomPadding(...)`                           | ✅      | ✅  | ❌  |
| `messengerShown` / `messengerHidden` events       | ❌      | ✅  | ✅  |

Additional notes:

- On the web, `getUnreadConversationCount(...)` returns the last value received from the change event, since the web SDK exposes the count only through a callback.
- The `messengerShown` and `messengerHidden` events are not available on Android because the Intercom Android SDK does not expose a window visibility hook.
- `setBottomPadding(...)` uses pixels on Android and points on iOS, matching the respective native SDK.

## FAQ

### Do I need an Intercom account to use this plugin?

Yes. This plugin wraps the official Intercom SDKs, which require an active [Intercom](https://www.intercom.com/) account, an app ID, and platform-specific API keys.

### How is this plugin different from other similar plugins?

This plugin uses Intercom's modern login APIs (`loginUnidentifiedUser(...)` and `loginUser(...)`). On Android it depends on the base SDK, so it coexists cleanly with your own Firebase Cloud Messaging or APNs setup and lets you forward push notifications to Intercom yourself. It also ships a fully typed web implementation, cross-platform push notification helpers, and is backed by dedicated support.

### Why does this plugin use `intercom-sdk-base` instead of `intercom-sdk` on Android?

The full `intercom-sdk` artifact automatically integrates Firebase Cloud Messaging by registering its own `FirebaseMessagingService`. This conflicts with apps that manage push notifications themselves (e.g. via `@capacitor-firebase/messaging`). The base artifact avoids this conflict and lets you forward push notifications to Intercom yourself.

### How does identity verification work?

Generate a user hash (HMAC) or a JSON Web Token (JWT) on your backend using your Intercom secret key, then pass it via `setUserHash(...)` or `setUserJwt(...)` **before** logging in the user. Never expose your secret key in your app.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Crisp](https://capawesome.io/docs/sdks/capacitor/crisp/): Unofficial Capacitor plugin for the Crisp live chat and customer support platform.
- [Formbricks](https://capawesome.io/docs/sdks/capacitor/formbricks/): Unofficial Capacitor plugin for Formbricks to run in-app surveys.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for the PostHog product analytics platform.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/intercom/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/intercom/LICENSE).

## Third-Party Notices

The Intercom Android and iOS SDKs are licensed under the Apache License 2.0 and are distributed via Maven Central, CocoaPods, and Swift Package Manager. The web SDK is licensed under the MIT license. This plugin only declares these SDKs as dependencies and does not bundle or modify them. Using the plugin requires an active Intercom account. The MIT license of this plugin covers the wrapper code only, not the Intercom SDKs.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Intercom Inc. or any of its affiliates or subsidiaries. "Intercom" is a trademark of Intercom Inc. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Intune Plugin

Unofficial Capacitor plugin for [Microsoft Intune](https://www.microsoft.com/en-us/security/business/microsoft-intune).[1](#fn:1)

## Features

The Capacitor Intune plugin integrates the Microsoft Intune App SDK for Mobile Application Management (MAM) into Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🛡️ **App Protection Policies**: Automatic enforcement of PIN, copy/paste and screenshot restrictions after the native integration.
- 🔐 **File Protection**: Encrypt, inspect and decrypt files through the Intune App SDK to honor the "Encrypt org data" policy on iOS, where the SDK does not encrypt files on its own.
- 🔑 **MSAL**: Acquire tokens interactively or silently via the Microsoft Authentication Library.
- 🧾 **Enrollment**: Register and enroll accounts in Mobile Application Management (MAM) — without device enrollment.
- 🚦 **App Protection Conditional Access**: Remediate compliance when Microsoft Entra ID requires an app protection policy before issuing tokens.
- 📋 **Typed Policy Introspection**: Read the applied app protection policy as typed booleans to adapt your UI.
- ⚙️ **App Configuration**: Read the application configuration deployed via the MAM channel, including conflict information.
- 🧹 **Selective Wipe Events**: Get notified when the Intune service requests a wipe so you can purge the web layer storage (e.g. IndexedDB, Local Storage) that the SDK cannot wipe itself.
- 🩺 **Diagnostics**: Show the Intune diagnostic console from JavaScript.
- 📌 **Current SDK Pins**: Built against current Microsoft Intune App SDK and MSAL versions — Microsoft blocks apps that ship outdated SDKs.
- 🤝 **Compatibility**: Works alongside the [Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/) plugin, which covers the MDM channel (see [Choosing between the MAM and MDM channel](#choosing-between-the-mam-and-mdm-channel)).
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Intune plugin is typically used in line-of-business apps that are distributed to employees of organizations that manage corporate data with Microsoft Intune, for example:

- **App protection without device enrollment**: Protect corporate data in your app on personal (BYOD) devices via Mobile Application Management (MAM).
- **Conditional access**: Combine with Microsoft Entra conditional access policies that require an Intune-protected app (see [Handle App Protection Conditional Access](#handle-app-protection-conditional-access)).
- **Policy-aware UI**: Read the applied app protection policy and hide or disable features (e.g. local export) that the policy does not allow.
- **Encrypt organization data**: Protect recordings, downloads and exports on iOS when the app protection policy requires file encryption.
- **Per-tenant configuration**: Read the application configuration that the organization's IT administrator has deployed for the signed-in account.
- **Selective wipe**: Clean up the web layer storage of your app when the organization wipes its corporate data.
- **Ionic enterprise migration**: Migrate from the discontinued Ionic enterprise Intune integration to a maintained, free plugin.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-intune` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-intune
npx cap sync
```

This plugin requires a [Microsoft Intune](https://www.microsoft.com/en-us/security/business/microsoft-intune) tenant with Intune licenses and an app registration in [Microsoft Entra ID](https://entra.microsoft.com/). Create the app registration in the Microsoft Entra admin center, note its **Application (client) ID** and configure the platform-specific redirect URIs (see below). The `acquireToken(...)` scopes you request must be exposed or granted on this app registration.

> [!IMPORTANT] The Intune App SDKs are developed and licensed by Microsoft (see [Third-Party Notices](#third-party-notices)). This plugin declares them as dependencies and downloads them from Microsoft's official repositories at build or install time. It does not bundle or modify them.

### Android

The Microsoft Intune App SDK for Android is downloaded automatically from [Microsoft's official GitHub repository](https://github.com/microsoftconnect/ms-intune-app-sdk-android) during the Gradle build. However, the Intune App SDK requires several changes to your app project that no plugin can make for you. Follow the steps below or use [Trapeze](#automated-setup-with-trapeze) to automate them.

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$intuneMamSdkVersion` version of the [Microsoft Intune App SDK for Android](https://github.com/microsoftconnect/ms-intune-app-sdk-android) (default: `12.4.0`)
- `$msalVersion` version of `com.microsoft.identity.client:msal` (default: `8.4.0`)

#### MAM Build Plugin

The Intune App SDK relies on a Gradle build plugin that rewrites the Android base classes of your app **and all Capacitor plugins** to their MAM equivalents. Only the app module can apply this plugin — it cannot be applied by a library. Add the following to the `buildscript` block of your `android/build.gradle` file:

```
 buildscript {
     repositories {
         google()
         mavenCentral()
+        ivy {
+            url 'https://raw.githubusercontent.com/microsoftconnect/ms-intune-app-sdk-android'
+            patternLayout { artifact '[revision]/GradlePlugin/[artifact].[ext]' }
+            metadataSources { artifact() }
+            content { includeGroup 'com.microsoft.intune.mam.build' }
+        }
     }
     dependencies {
         classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'org.javassist:javassist:3.29.2-GA'
+        classpath 'com.microsoft.intune.mam.build:com.microsoft.intune.mam.build:12.4.0@jar'
     }
 }
```

Then apply the plugin in your `android/app/build.gradle` file:

```
 apply plugin: 'com.android.application'
+apply plugin: 'com.microsoft.intune.mam'
```

#### Application Class

The Intune App SDK requires an `Application` class that registers the MAM components before any other code runs. Set the ready-made class provided by this plugin in the `application` tag of your `android/app/src/main/AndroidManifest.xml` file:

```
<application
    android:name="io.capawesome.capacitorjs.plugins.intune.IntuneApplication"
    ...>
```

If your app already uses a custom `Application` class, call the initializer yourself instead:

```
import io.capawesome.capacitorjs.plugins.intune.Intune;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Intune.initialize(this);
    }
}
```

It's also recommended to disable predictive back gestures in the `application` tag since the Intune App SDK does not support them yet:

```
<application
    android:enableOnBackInvokedCallback="false"
    ...>
```

#### MSAL Configuration

Create the file `android/app/src/main/res/raw/auth_config.json` with your MSAL configuration:

```
{
  "client_id": "YOUR_CLIENT_ID",
  "authorization_user_agent": "DEFAULT",
  "redirect_uri": "msauth://YOUR_PACKAGE_NAME/YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE",
  "account_mode": "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "client_capabilities": "protapp",
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADMultipleOrgs"
      }
    }
  ]
}
```

The `client_capabilities` entry declares that your app supports [App Protection Conditional Access](#handle-app-protection-conditional-access). On iOS, the plugin declares it automatically.

You can generate the base64-encoded signature hash of your signing key with:

```
keytool -exportcert -alias YOUR_KEY_ALIAS -keystore YOUR_KEYSTORE | openssl sha1 -binary | openssl base64
```

Make sure the same redirect URI (`msauth://YOUR_PACKAGE_NAME/YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE`) is registered as an **Android** platform redirect URI on your app registration in the Microsoft Entra admin center.

Next, add the following activity to the `application` tag of your `android/app/src/main/AndroidManifest.xml` file so that MSAL can receive the redirect from the Microsoft sign-in flow:

```
<activity android:name="com.microsoft.identity.client.BrowserTabActivity" android:exported="true">
    <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="msauth" android:host="YOUR_PACKAGE_NAME" android:path="/YOUR_BASE64_ENCODED_PACKAGE_SIGNATURE" />
    </intent-filter>
</activity>
```

#### Gradle Properties

Add the following to your `android/gradle.properties` file. Without it, release builds may report `MAM Enabled: No` in the diagnostic console:

```
android.enableResourceOptimizations=false
```

#### Company Portal

App protection policies are only applied when the [Company Portal](https://play.google.com/store/apps/details?id=com.microsoft.windowsintune.companyportal) app is installed on the device. The user does **not** need to sign in to the Company Portal. Without it, your app behaves as unmanaged.

### iOS

The Microsoft Intune App SDK for iOS requires **iOS 17+** as deployment target and a current Xcode version. This deviates from the usual iOS 15 minimum of the Capawesome plugin collection. Make sure the deployment target of your app is set to iOS 17.0 or later (in `ios/App/App.xcodeproj` and, if you use Swift Package Manager, in `ios/App/CapApp-SPM/Package.swift`).

The SDK is consumed from [Microsoft's official GitHub repository](https://github.com/msintuneappsdk/ms-intune-app-sdk-ios): via Swift Package Manager it is resolved like any other package; via CocoaPods it is downloaded automatically during `pod install` (Microsoft does not publish a CocoaPods pod).

#### Info.plist

Add the `IntuneMAMSettings` dictionary to your `ios/App/App/Info.plist` file (the keys keep their legacy `ADAL` names for historical reasons):

```
<key>IntuneMAMSettings</key>
<dict>
    <key>ADALAuthority</key>
    <string>https://login.microsoftonline.com/YOUR_TENANT_ID</string>
    <key>ADALClientId</key>
    <string>YOUR_CLIENT_ID</string>
    <key>ADALRedirectUri</key>
    <string>msauth.YOUR_BUNDLE_ID://auth</string>
</dict>
```

This plugin also uses these values to configure MSAL, so no separate MSAL configuration is needed.

Next, register the MSAL redirect URL scheme and the query schemes in the same file:

```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>MSAL</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.YOUR_BUNDLE_ID</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>msauthv2</string>
    <string>msauthv3</string>
    <string>http-intunemam</string>
    <string>https-intunemam</string>
</array>
```

Make sure the redirect URI (`msauth.YOUR_BUNDLE_ID://auth`) is registered as an **iOS/macOS** platform redirect URI on your app registration in the Microsoft Entra admin center. The plugin handles the MSAL redirect automatically — no `AppDelegate` changes are required.

Finally, add a Face ID usage description if your app does not have one yet, since app protection policies may require biometric unlock:

```
<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to secure corporate data.</string>
```

#### Keychain Sharing

Enable the **Keychain Sharing** capability for your app target in Xcode and add the following keychain groups (in this order):

1. `com.example.app` (your bundle ID, usually already present)
1. `com.microsoft.intune.mam`
1. `com.microsoft.adalcache`

#### IntuneMAMConfigurator

Microsoft ships the `IntuneMAMConfigurator` tool with the [SDK repository](https://github.com/msintuneappsdk/ms-intune-app-sdk-ios). It applies the minimum required `Info.plist` changes for Intune management (including the `-intunemam` query scheme variants for every scheme your app queries) and is idempotent:

```
IntuneMAMConfigurator -i ios/App/App/Info.plist -e ios/App/App/App.entitlements
```

Running it is recommended before you ship, especially if your app passes additional URL schemes to `canOpenURL`.

### Automated Setup with Trapeze

Most of the host app changes above can be automated with [Trapeze](https://trapeze.dev/), which is also used by [Capawesome Cloud](https://capawesome.io/cloud/). Save the following configuration as `trapeze.yaml` and run `npx @trapezedev/configure run trapeze.yaml` with the `CLIENT_ID`, `TENANT_ID`, `PACKAGE_NAME`, `BUNDLE_ID` and `SIGNATURE_HASH` variables set:

```
vars:
  CLIENT_ID:
  TENANT_ID:
  PACKAGE_NAME:
  BUNDLE_ID:
  SIGNATURE_HASH:

platforms:
  android:
    gradle:
      - file: build.gradle
        target:
          buildscript:
            dependencies:
        insert: |
          classpath 'org.javassist:javassist:3.29.2-GA'
          classpath 'com.microsoft.intune.mam.build:com.microsoft.intune.mam.build:12.4.0@jar'
      - file: build.gradle
        target:
          buildscript:
            repositories:
        insert: |
          ivy {
              url 'https://raw.githubusercontent.com/microsoftconnect/ms-intune-app-sdk-android'
              patternLayout { artifact '[revision]/GradlePlugin/[artifact].[ext]' }
              metadataSources { artifact() }
              content { includeGroup 'com.microsoft.intune.mam.build' }
          }
      - file: app/build.gradle
        target:
        insert: |
          apply plugin: 'com.microsoft.intune.mam'
    manifest:
      - file: AndroidManifest.xml
        target: manifest/application
        attrs:
          android:name: io.capawesome.capacitorjs.plugins.intune.IntuneApplication
          android:enableOnBackInvokedCallback: 'false'
      - file: AndroidManifest.xml
        target: manifest/application
        inject: |
          <activity android:name="com.microsoft.identity.client.BrowserTabActivity" android:exported="true">
            <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="msauth" android:host="$PACKAGE_NAME" android:path="/$SIGNATURE_HASH" />
            </intent-filter>
          </activity>
    res:
      - path: raw
        file: auth_config.json
        text: |
          {
            "client_id": "$CLIENT_ID",
            "authorization_user_agent": "DEFAULT",
            "redirect_uri": "msauth://$PACKAGE_NAME/$SIGNATURE_HASH",
            "account_mode": "MULTIPLE",
            "broker_redirect_uri_registered": true,
            "client_capabilities": "protapp",
            "authorities": [
              {
                "type": "AAD",
                "audience": {
                  "type": "AzureADMultipleOrgs"
                }
              }
            ]
          }
  ios:
    targets:
      App:
        buildSettings:
          IPHONEOS_DEPLOYMENT_TARGET: '17.0'
        entitlements:
          - keychain-access-groups:
              [
                '$BUNDLE_ID',
                'com.microsoft.intune.mam',
                'com.microsoft.adalcache',
              ]
        plist:
          - entries:
              - IntuneMAMSettings:
                  ADALAuthority: https://login.microsoftonline.com/$TENANT_ID
                  ADALClientId: $CLIENT_ID
                  ADALRedirectUri: msauth.$BUNDLE_ID://auth
              - CFBundleURLTypes:
                  - CFBundleURLName: MSAL
                    CFBundleURLSchemes:
                      - msauth.$BUNDLE_ID
              - LSApplicationQueriesSchemes:
                  - msauthv2
                  - msauthv3
                  - http-intunemam
                  - https-intunemam
              - NSFaceIDUsageDescription: This app uses Face ID to secure corporate data.
```

> [!NOTE] Trapeze cannot edit `gradle.properties`, so the [Gradle Properties](#gradle-properties) step must still be done manually. Review the result after running Trapeze: some list-valued Info.plist entries may be merged rather than replaced, and the Gradle insertions are not idempotent — run them only once.

### Web

This plugin does not provide a web implementation. All methods reject with an `unimplemented` error on the web platform.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Sign in and enroll an account

Acquire a token via MSAL and enroll the returned account in Mobile Application Management (MAM). The enrollment itself is asynchronous — listen for the `enrollmentChange` event to get the result:

```
import { Intune } from '@capawesome/capacitor-intune';

const signInAndEnroll = async () => {
  await Intune.addListener('enrollmentChange', event => {
    console.log('Enrollment status:', event.status);
  });
  const { accountId } = await Intune.acquireToken({
    scopes: ['https://graph.microsoft.com/.default'],
  });
  await Intune.registerAndEnrollAccount({ accountId });
};
```

### Handle App Protection Conditional Access

If your organization requires an app protection policy via Conditional Access, Microsoft Entra ID only issues tokens once Intune manages the app. In this case, the token acquisition is rejected with the `PROTECTION_POLICY_REQUIRED` error code. Remediate the compliance and retry the token acquisition:

```
import { ErrorCode, Intune } from '@capawesome/capacitor-intune';

const acquireToken = async (scopes: string[]) => {
  try {
    return await Intune.acquireToken({ scopes });
  } catch (error) {
    if (error.code !== ErrorCode.ProtectionPolicyRequired) {
      throw error;
    }
    const { status } = await Intune.remediateCompliance(error.data);
    if (status !== 'compliant') {
      throw error;
    }
    return Intune.acquireTokenSilent({ accountId: error.data.accountId, scopes });
  }
};
```

### Read the app protection policy

Adapt your UI to the applied app protection policy:

```
import { Intune } from '@capawesome/capacitor-intune';

const applyPolicy = async () => {
  const { account } = await Intune.getEnrolledAccount();
  if (!account) {
    return;
  }
  const policy = await Intune.getPolicy({ accountId: account.accountId });
  if (!policy.saveToPersonalStorageAllowed) {
    // Hide your export/download buttons.
  }
};
```

### Protect files

On iOS, the Intune App SDK does not encrypt files on its own. Protect every file that contains organization data, and decrypt it before handing it to other plugins or native components:

```
import { Intune } from '@capawesome/capacitor-intune';

const protectFile = async (path: string) => {
  const { account } = await Intune.getEnrolledAccount();
  if (!account) {
    return;
  }
  await Intune.protectFile({ path, accountId: account.accountId });
};

const decryptFile = async (path: string, destination: string) => {
  const { encrypted } = await Intune.isFileEncrypted({ path });
  if (encrypted) {
    await Intune.decryptFile({ path, destination });
  }
};
```

### Read the app configuration

Read the configuration values that the organization's IT administrator has deployed:

```
import { Intune } from '@capawesome/capacitor-intune';

const readAppConfig = async () => {
  const { account } = await Intune.getEnrolledAccount();
  if (!account) {
    return;
  }
  const { values } = await Intune.getAppConfig({ accountId: account.accountId });
  console.log('Server URL:', values['com.example.serverUrl']);
};
```

### Handle selective wipe

The Intune App SDK wipes the data it manages, but it does **not** wipe the web layer storage of your Capacitor app. Register the `wipeRequested` listener as early as possible and purge your web storage when it fires:

```
import { Intune } from '@capawesome/capacitor-intune';

const registerWipeListener = async () => {
  await Intune.addListener('wipeRequested', async () => {
    localStorage.clear();
    sessionStorage.clear();
    const databases = await indexedDB.databases();
    for (const database of databases) {
      if (database.name) {
        indexedDB.deleteDatabase(database.name);
      }
    }
  });
};
```

## API

- [`acquireToken(...)`](#acquiretoken)
- [`acquireTokenSilent(...)`](#acquiretokensilent)
- [`decryptFile(...)`](#decryptfile)
- [`getAppConfig(...)`](#getappconfig)
- [`getEnrolledAccount()`](#getenrolledaccount)
- [`getPolicy(...)`](#getpolicy)
- [`getSdkVersion()`](#getsdkversion)
- [`isFileEncrypted(...)`](#isfileencrypted)
- [`loginAndEnrollAccount()`](#loginandenrollaccount)
- [`protectFile(...)`](#protectfile)
- [`registerAndEnrollAccount(...)`](#registerandenrollaccount)
- [`remediateCompliance(...)`](#remediatecompliance)
- [`showDiagnosticConsole()`](#showdiagnosticconsole)
- [`unenrollAccount(...)`](#unenrollaccount)
- [`addListener('appConfigChange', ...)`](#addlistenerappconfigchange-)
- [`addListener('enrollmentChange', ...)`](#addlistenerenrollmentchange-)
- [`addListener('policyChange', ...)`](#addlistenerpolicychange-)
- [`addListener('wipeRequested', ...)`](#addlistenerwiperequested-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### acquireToken(...)

```
acquireToken(options: AcquireTokenOptions) => Promise<AcquireTokenResult>
```

Acquire an access token interactively via the Microsoft Authentication Library (MSAL).

This presents the Microsoft sign-in UI if necessary. Use the returned `accountId` to enroll the account via `registerAndEnrollAccount(...)`.

If the tenant requires an app protection policy, the call is rejected with the `PROTECTION_POLICY_REQUIRED` error code. Use `remediateCompliance(...)` in this case.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `AcquireTokenOptions` |

**Returns:** `Promise<AcquireTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### acquireTokenSilent(...)

```
acquireTokenSilent(options: AcquireTokenSilentOptions) => Promise<AcquireTokenResult>
```

Acquire an access token silently via the Microsoft Authentication Library (MSAL) for an already signed-in account.

If the tenant requires an app protection policy, the call is rejected with the `PROTECTION_POLICY_REQUIRED` error code. Use `remediateCompliance(...)` in this case.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `AcquireTokenSilentOptions` |

**Returns:** `Promise<AcquireTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### decryptFile(...)

```
decryptFile(options: DecryptFileOptions) => Promise<void>
```

Decrypt a file that was encrypted by the Intune App SDK.

On iOS, encrypted files can only be read through the Intune App SDK. Call this method before handing a file to other consumers such as the Filesystem plugin, a media player or an uploader.

On Android, the app reads encrypted files transparently, so this method is rarely needed. The file is tagged with the unmanaged identity, which removes the encryption and takes the file out of the scope of a selective wipe.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `DecryptFileOptions` |

**Since:** 0.1.1

______________________________________________________________________

### getAppConfig(...)

```
getAppConfig(options: GetAppConfigOptions) => Promise<GetAppConfigResult>
```

Get the application configuration values that the organization's IT administrator has deployed for the given account via the MAM channel.

For configuration deployed via the MDM channel (device enrollment), use the Managed Configurations plugin instead.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GetAppConfigOptions` |

**Returns:** `Promise<GetAppConfigResult>`

**Since:** 0.1.0

______________________________________________________________________

### getEnrolledAccount()

```
getEnrolledAccount() => Promise<GetEnrolledAccountResult>
```

Get the account that is currently enrolled in Mobile Application Management (MAM).

Only available on Android and iOS.

**Returns:** `Promise<GetEnrolledAccountResult>`

**Since:** 0.1.0

______________________________________________________________________

### getPolicy(...)

```
getPolicy(options: GetPolicyOptions) => Promise<GetPolicyResult>
```

Get the app protection policy that is currently applied for the given account.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GetPolicyOptions` |

**Returns:** `Promise<GetPolicyResult>`

**Since:** 0.1.0

______________________________________________________________________

### getSdkVersion()

```
getSdkVersion() => Promise<GetSdkVersionResult>
```

Get the versions of the Intune App SDK and the Microsoft Authentication Library (MSAL) that the plugin was built with.

Only available on Android and iOS.

**Returns:** `Promise<GetSdkVersionResult>`

**Since:** 0.1.0

______________________________________________________________________

### isFileEncrypted(...)

```
isFileEncrypted(options: IsFileEncryptedOptions) => Promise<IsFileEncryptedResult>
```

Check whether a file is encrypted by the Intune App SDK.

On Android, this reflects whether the file is tagged with a managed identity whose app protection policy uses file encryption, since the Intune App SDK for Android does not expose the encryption state of a single file.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `IsFileEncryptedOptions` |

**Returns:** `Promise<IsFileEncryptedResult>`

**Since:** 0.1.1

______________________________________________________________________

### loginAndEnrollAccount()

```
loginAndEnrollAccount() => Promise<void>
```

Sign in and enroll an account using the login UI provided by the Intune App SDK.

On Android, use `acquireToken(...)` followed by `registerAndEnrollAccount(...)` instead.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### protectFile(...)

```
protectFile(options: ProtectFileOptions) => Promise<void>
```

Protect a file or directory for the given account.

On iOS, the Intune App SDK does not encrypt files on its own. Call this method for every file that contains organization data if the app protection policy requires file encryption (see `GetPolicyResult.fileEncryptionRequired`). The file is encrypted in place if the policy requires it. For a directory, all files it currently contains are protected; files added later must be protected separately. Encrypted files can only be read through the Intune App SDK, so use `decryptFile(...)` before reading them with other plugins.

On Android, the Intune App SDK encrypts files automatically and the app reads them transparently. This method tags the file or directory with the account so that it is in the scope of a selective wipe. Files added to a protected directory later inherit the protection.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `ProtectFileOptions` |

**Since:** 0.1.1

______________________________________________________________________

### registerAndEnrollAccount(...)

```
registerAndEnrollAccount(options: RegisterAndEnrollAccountOptions) => Promise<void>
```

Register an account for Mobile Application Management (MAM) and enroll it in the Intune service.

Call this after a successful `acquireToken(...)` call. The enrollment itself is asynchronous; listen for the `enrollmentChange` event to get the enrollment result.

Only available on Android and iOS.

| Param         | Type                              |
| ------------- | --------------------------------- |
| **`options`** | `RegisterAndEnrollAccountOptions` |

**Since:** 0.1.0

______________________________________________________________________

### remediateCompliance(...)

```
remediateCompliance(options: RemediateComplianceOptions) => Promise<RemediateComplianceResult>
```

Bring the app into compliance with the app protection policy of an account so that Microsoft Entra ID grants tokens for it.

Call this when `acquireToken(...)` or `acquireTokenSilent(...)` is rejected with the `PROTECTION_POLICY_REQUIRED` error code, passing the `data` of the error as options. The Intune App SDK registers and enrolls the account as needed. If the returned status is `compliant`, retry the token acquisition.

On iOS, the Intune App SDK may restart the app during the remediation if the account was not enrolled before. In that case, the promise is never settled and the app should retry the sign-in after the restart.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `RemediateComplianceOptions` |

**Returns:** `Promise<RemediateComplianceResult>`

**Since:** 0.1.2

______________________________________________________________________

### showDiagnosticConsole()

```
showDiagnosticConsole() => Promise<void>
```

Show the diagnostic console of the Intune App SDK.

The console allows the user to inspect the SDK state and collect logs for support requests.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### unenrollAccount(...)

```
unenrollAccount(options: UnenrollAccountOptions) => Promise<void>
```

Unenroll an account from Mobile Application Management (MAM) and unregister it from the Intune service.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `UnenrollAccountOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('appConfigChange', ...)

```
addListener(eventName: 'appConfigChange', listenerFunc: (event: AppConfigChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the application configuration changes.

Use `getAppConfig(...)` to read the new configuration values.

Only available on Android and iOS.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'appConfigChange'`                     |
| **`listenerFunc`** | `(event: AppConfigChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('enrollmentChange', ...)

```
addListener(eventName: 'enrollmentChange', listenerFunc: (event: EnrollmentChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the enrollment state of an account changes, for example when an enrollment attempt succeeds or fails.

Only available on Android and iOS.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'enrollmentChange'`                     |
| **`listenerFunc`** | `(event: EnrollmentChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('policyChange', ...)

```
addListener(eventName: 'policyChange', listenerFunc: (event: PolicyChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the app protection policy changes.

Use `getPolicy(...)` to read the new policy values.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'policyChange'`                     |
| **`listenerFunc`** | `(event: PolicyChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('wipeRequested', ...)

```
addListener(eventName: 'wipeRequested', listenerFunc: (event: WipeRequestedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the Intune service requests a selective wipe of the account's data.

The Intune App SDK wipes the data it manages, but it does **not** wipe the web layer storage of your Capacitor app (e.g. IndexedDB, Local Storage). Use this event to clean up any data your web code has persisted.

The event is delivered even if the wipe was requested while your app was not running (see the documentation for details).

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'wipeRequested'`                     |
| **`listenerFunc`** | `(event: WipeRequestedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AcquireTokenResult

| Prop              | Type     | Description                                                                                                             | Since                                                                  |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **`accessToken`** | `string` | The acquired access token.                                                                                              | 0.1.0                                                                  |
| **`accountId`**   | `string` | The Microsoft Entra object ID (OID) of the signed-in account. Use this identifier for all other methods of this plugin. | 0.1.0                                                                  |
| **`idToken`**     | \`string | null\`                                                                                                                  | The raw ID token of the signed-in account, if available.               |
| **`tenantId`**    | \`string | null\`                                                                                                                  | The Microsoft Entra tenant ID of the signed-in account, if available.  |
| **`username`**    | \`string | null\`                                                                                                                  | The username (usually the UPN) of the signed-in account, if available. |

#### AcquireTokenOptions

| Prop              | Type       | Description                                                                                            | Default | Since |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`forcePrompt`** | `boolean`  | Whether or not to force the account selection prompt to be shown, even if a user is already signed in. | `false` | 0.1.0 |
| **`loginHint`**   | `string`   | The username to pre-fill in the sign-in UI.                                                            |         | 0.1.0 |
| **`scopes`**      | `string[]` | The scopes to request the access token for.                                                            |         | 0.1.0 |

#### AcquireTokenSilentOptions

| Prop               | Type       | Description                                                                  | Default | Since |
| ------------------ | ---------- | ---------------------------------------------------------------------------- | ------- | ----- |
| **`accountId`**    | `string`   | The Microsoft Entra object ID (OID) of the account to acquire the token for. |         | 0.1.0 |
| **`forceRefresh`** | `boolean`  | Whether or not to ignore any cached token and force a token refresh.         | `false` | 0.1.0 |
| **`scopes`**       | `string[]` | The scopes to request the access token for.                                  |         | 0.1.0 |

#### DecryptFileOptions

| Prop              | Type     | Description                                                                                                                                                             | Since |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`destination`** | `string` | The absolute path or `file://` URI to write the decrypted copy to. If not provided, the file is decrypted in place. An existing file at the destination is overwritten. | 0.1.1 |
| **`path`**        | `string` | The absolute path or `file://` URI of the encrypted file.                                                                                                               | 0.1.1 |

#### GetAppConfigResult

| Prop            | Type                     | Description                                                                                                                             | Since |
| --------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`conflicts`** | `AppConfigConflict[]`    | The configuration keys for which multiple conflicting values have been deployed.                                                        | 0.1.0 |
| **`values`**    | `Record<string, string>` | The merged application configuration values. For keys with conflicting values, the value that the Intune App SDK returns first is used. | 0.1.0 |

#### AppConfigConflict

| Prop         | Type       | Description                                                   | Since |
| ------------ | ---------- | ------------------------------------------------------------- | ----- |
| **`key`**    | `string`   | The configuration key for which conflicting values exist.     | 0.1.0 |
| **`values`** | `string[]` | All values that have been deployed for the configuration key. | 0.1.0 |

#### GetAppConfigOptions

| Prop            | Type     | Description                                                                                  | Since |
| --------------- | -------- | -------------------------------------------------------------------------------------------- | ----- |
| **`accountId`** | `string` | The Microsoft Entra object ID (OID) of the account to get the application configuration for. | 0.1.0 |

#### GetEnrolledAccountResult

| Prop          | Type              | Description | Since                                                     |
| ------------- | ----------------- | ----------- | --------------------------------------------------------- |
| **`account`** | \`EnrolledAccount | null\`      | The enrolled account or `null` if no account is enrolled. |

#### EnrolledAccount

| Prop            | Type     | Description                                                  | Since                                                                 |
| --------------- | -------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| **`accountId`** | `string` | The Microsoft Entra object ID (OID) of the enrolled account. | 0.1.0                                                                 |
| **`username`**  | \`string | null\`                                                       | The username (usually the UPN) of the enrolled account, if available. |

#### GetPolicyResult

| Prop                               | Type      | Description                                                                                                                      | Since |
| ---------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`contactSyncAllowed`**           | `boolean` | Whether or not the policy allows syncing contacts to the device.                                                                 | 0.1.0 |
| **`fileEncryptionRequired`**       | `boolean` | Whether or not the policy requires files to be encrypted. On Android, this reflects whether file encryption is currently in use. | 0.1.0 |
| **`managedBrowserRequired`**       | `boolean` | Whether or not the policy requires links to be opened in a managed browser (e.g. Microsoft Edge).                                | 0.1.0 |
| **`pinRequired`**                  | `boolean` | Whether or not the policy requires a PIN to access the app.                                                                      | 0.1.0 |
| **`saveToPersonalStorageAllowed`** | `boolean` | Whether or not the policy allows saving files to personal (local) storage.                                                       | 0.1.0 |
| **`screenCaptureAllowed`**         | `boolean` | Whether or not the policy allows taking screenshots.                                                                             | 0.1.0 |

#### GetPolicyOptions

| Prop            | Type     | Description                                                                              | Since |
| --------------- | -------- | ---------------------------------------------------------------------------------------- | ----- |
| **`accountId`** | `string` | The Microsoft Entra object ID (OID) of the account to get the app protection policy for. | 0.1.0 |

#### GetSdkVersionResult

| Prop                   | Type     | Description                        | Since                                                                     |
| ---------------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------- |
| **`intuneSdkVersion`** | `string` | The version of the Intune App SDK. | 0.1.0                                                                     |
| **`msalVersion`**      | \`string | null\`                             | The version of the Microsoft Authentication Library (MSAL), if available. |

#### IsFileEncryptedResult

| Prop            | Type      | Description                                                 | Since |
| --------------- | --------- | ----------------------------------------------------------- | ----- |
| **`encrypted`** | `boolean` | Whether or not the file is encrypted by the Intune App SDK. | 0.1.1 |

#### IsFileEncryptedOptions

| Prop       | Type     | Description                                              | Since |
| ---------- | -------- | -------------------------------------------------------- | ----- |
| **`path`** | `string` | The absolute path or `file://` URI of the file to check. | 0.1.1 |

#### ProtectFileOptions

| Prop            | Type     | Description                                                             | Since |
| --------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`accountId`** | `string` | The Microsoft Entra object ID (OID) of the account that owns the file.  | 0.1.1 |
| **`path`**      | `string` | The absolute path or `file://` URI of the file or directory to protect. | 0.1.1 |

#### RegisterAndEnrollAccountOptions

| Prop            | Type     | Description                                                                                                    | Since |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----- |
| **`accountId`** | `string` | The Microsoft Entra object ID (OID) of the account to register and enroll, as returned by `acquireToken(...)`. | 0.1.0 |

#### RemediateComplianceResult

| Prop               | Type               | Description                                                 | Since                                                                                                      |
| ------------------ | ------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **`errorMessage`** | \`string           | null\`                                                      | A localized error message that can be displayed to the user if the account is not compliant, if available. |
| **`errorTitle`**   | \`string           | null\`                                                      | A localized error title that can be displayed to the user if the account is not compliant, if available.   |
| **`status`**       | `ComplianceStatus` | The compliance status of the account after the remediation. | 0.1.2                                                                                                      |

#### RemediateComplianceOptions

| Prop            | Type      | Description                                                                                                                                                                                     | Default | Since |
| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`accountId`** | `string`  | The Microsoft Entra object ID (OID) of the account to remediate.                                                                                                                                |         | 0.1.2 |
| **`authority`** | `string`  | The authority URL of the account. Only available on Android. Required on Android.                                                                                                               |         | 0.1.2 |
| **`silent`**    | `boolean` | Whether or not to remediate without showing any UI of the Intune App SDK. On iOS, the status `interactionRequired` is returned if the remediation cannot be completed without user interaction. | `false` | 0.1.2 |
| **`tenantId`**  | `string`  | The Microsoft Entra tenant ID of the account. Only available on Android. Required on Android.                                                                                                   |         | 0.1.2 |
| **`username`**  | `string`  | The username (usually the UPN) of the account. Only available on Android. Required on Android.                                                                                                  |         | 0.1.2 |

#### UnenrollAccountOptions

| Prop            | Type      | Description                                                                                           | Default | Since |
| --------------- | --------- | ----------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`accountId`** | `string`  | The Microsoft Entra object ID (OID) of the account to unenroll.                                       |         | 0.1.0 |
| **`wipe`**      | `boolean` | Whether or not the account's data should be wiped as part of the unenrollment. Only available on iOS. | `false` | 0.1.0 |

#### PluginListenerHandle

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

#### AppConfigChangeEvent

| Prop            | Type     | Description | Since                                                                      |
| --------------- | -------- | ----------- | -------------------------------------------------------------------------- |
| **`accountId`** | \`string | null\`      | The Microsoft Entra object ID (OID) of the affected account, if available. |

#### EnrollmentChangeEvent

| Prop            | Type               | Description                               | Since                                                                      |
| --------------- | ------------------ | ----------------------------------------- | -------------------------------------------------------------------------- |
| **`accountId`** | \`string           | null\`                                    | The Microsoft Entra object ID (OID) of the affected account, if available. |
| **`status`**    | `EnrollmentStatus` | The new enrollment status of the account. | 0.1.0                                                                      |

#### PolicyChangeEvent

| Prop            | Type     | Description | Since                                                                      |
| --------------- | -------- | ----------- | -------------------------------------------------------------------------- |
| **`accountId`** | \`string | null\`      | The Microsoft Entra object ID (OID) of the affected account, if available. |

#### WipeRequestedEvent

| Prop            | Type     | Description | Since                                                                      |
| --------------- | -------- | ----------- | -------------------------------------------------------------------------- |
| **`accountId`** | \`string | null\`      | The Microsoft Entra object ID (OID) of the affected account, if available. |

### Type Aliases

#### ComplianceStatus

The compliance status of an account.

- `canceled`: The user canceled the remediation. Only available on iOS.
- `clientError`: The remediation failed due to a client issue, such as a missing or invalid token. Only available on Android.
- `companyPortalRequired`: The Company Portal app must be installed. If it is already installed, the app must be restarted. Only available on Android.
- `compliant`: The account is compliant. Retry the token acquisition.
- `interactionRequired`: The remediation requires user interaction. Call `remediateCompliance(...)` again with `silent` set to `false`. Only available on iOS.
- `networkFailure`: The Intune service could not be reached. Retry when the network connection is restored.
- `notCompliant`: The account is not compliant.
- `pending`: The Intune service did not respond in time. Retry later. Only available on Android.
- `serviceFailure`: The compliance data could not be retrieved from the Intune service. Retry later.
- `unknown`: The status is unknown. Only available on Android.

`'canceled' | 'clientError' | 'companyPortalRequired' | 'compliant' | 'interactionRequired' | 'networkFailure' | 'notCompliant' | 'pending' | 'serviceFailure' | 'unknown'`

#### EnrollmentStatus

The enrollment status of an account.

`'enrolled' | 'failed' | 'pending' | 'unenrolled'`

## Platform Support

Not every feature is available on all platforms. The following table lists the notable per-platform differences of the plugin's API:

| Method / Option                        | Android | iOS | Web |
| -------------------------------------- | ------- | --- | --- |
| `loginAndEnrollAccount()`              | ❌      | ✅  | ❌  |
| `unenrollAccount(...)` (`wipe` option) | ❌      | ✅  | ❌  |

Additional notes:

- On Android, use `acquireToken(...)` followed by `registerAndEnrollAccount(...)` instead of `loginAndEnrollAccount()`. The Intune App SDK for Android does not provide its own login UI.
- On Android, `remediateCompliance(...)` requires the `authority`, `tenantId` and `username` options. All of them are included in the `data` of the `PROTECTION_POLICY_REQUIRED` error.
- On Android, `fileEncryptionRequired` reflects whether file encryption is currently **in use** by the Intune App SDK, which is the closest equivalent the SDK exposes.
- The `wipeRequested` event is persisted and replayed on the next app launch if no listener was registered when the wipe arrived. In rare cases the event may be delivered more than once, so make sure your wipe handler is idempotent.
- On iOS, the Intune App SDK does not encrypt files on its own. Call `protectFile(...)` for every file that contains organization data. On Android, file encryption is automatic and `protectFile(...)` only tags the file with the account so that it is in the scope of a selective wipe.
- On iOS, encrypted files can only be read through the Intune App SDK. Reading them with the Filesystem plugin or handing them to other native plugins (e.g. media players or uploaders) yields the encrypted content. Call `decryptFile(...)` first. On Android, the app reads encrypted files transparently, so `decryptFile(...)` is rarely needed.
- On Android, `isFileEncrypted(...)` reflects whether the file is tagged with a managed identity whose policy uses file encryption, since the Intune App SDK does not expose the encryption state of a single file.
- Policy **enforcement** (PIN, copy/paste and screenshot restrictions, etc.) is performed automatically by the Intune App SDK once the native integration is in place. The JavaScript API exists for the parts that enforcement cannot do: enrolling accounts, reading configuration, adapting your UI to the policy, protecting files on iOS, and cleaning up web storage on selective wipe.

## Choosing between the MAM and MDM channel

Organizations can deliver app configuration through two different channels, and administrators frequently mix them up. This plugin covers the **MAM channel**; the [Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/) plugin covers the **MDM channel**:

|                            | MAM channel (this plugin)                       | MDM channel ([Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/)) |
| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Device enrollment required | No                                              | Yes                                                                                                       |
| Delivered via              | Intune App SDK (Intune service)                 | `RestrictionsManager` / `com.apple.configuration.managed`                                                 |
| Targeted at                | The signed-in account (identity)                | The device                                                                                                |
| EMM vendor                 | Microsoft Intune only                           | Any EMM/MDM vendor                                                                                        |
| Typical scenario           | BYOD / app protection without device management | Corporate-owned, fully managed devices                                                                    |

If your organization deploys the app configuration policy with **"Managed apps"** as the delivery channel in the Intune admin center, use this plugin. If it is deployed with **"Managed devices"**, use the Managed Configurations plugin. Apps that must support both scenarios should read both channels.

## Testing

Exercising Mobile Application Management (MAM) requires infrastructure that cannot be simulated locally:

- A **Microsoft Intune tenant** with **Intune licenses** and a **licensed test user**.
- An **app protection policy** and (optionally) an **app configuration policy** targeted at the test user and your app.
- On Android, the **Company Portal** app installed on the test device.

Without a tenant, the plugin compiles and loads, but enrollment fails with `AccountNotLicensed`-style errors and no policy is applied. Building this plugin (e.g. via `npm run verify`) only proves that the code compiles — it does not exercise any MAM functionality.

## FAQ

### How is this plugin different from other similar plugins?

It integrates the Microsoft Intune App SDK for Mobile Application Management on Android and iOS through a fully typed API, enforcing app protection policies and exposing them as typed booleans so you can adapt your UI, acquiring tokens via MSAL, and enrolling accounts without device enrollment. It emits selective-wipe events so you can purge the web-layer storage (such as IndexedDB and Local Storage) that the SDK cannot reach itself, and it is built against current Intune and MSAL versions, which matters because Microsoft blocks apps that ship outdated SDKs. It is a free, actively maintained plugin that stays current with the latest Capacitor version.

### Do I need a Microsoft Intune tenant to use this plugin?

Yes. This plugin wraps the Microsoft Intune App SDK, which requires a Microsoft Intune tenant, Intune licenses, and an app registration in Microsoft Entra ID (see [Testing](#testing)).

### Why does the plugin require iOS 17?

The current Microsoft Intune App SDK for iOS requires iOS 17 or later. Microsoft actively blocks apps built with outdated Intune App SDK versions, so this plugin always tracks Microsoft's current SDK line instead of pinning an older one.

### Does this plugin enforce the app protection policies?

Mostly, yes. Once the native integration (MAM build plugin on Android, SDK integration on iOS) is in place, the Intune App SDK enforces PIN, data transfer and screenshot restrictions itself. File encryption is automatic on Android, but on iOS the app must protect its files via `protectFile(...)`. The JavaScript API of this plugin is for the parts enforcement cannot do: enrollment, introspection, file protection on iOS, and cleaning up web storage on selective wipe.

### What is the difference between this plugin and the Managed Configurations plugin?

This plugin reads the MAM channel (Intune App SDK, no device enrollment required). The [Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/) plugin reads the MDM channel (device enrollment required, works with any EMM vendor). See [Choosing between the MAM and MDM channel](#choosing-between-the-mam-and-mdm-channel).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API and App Attest.
- [Managed Configurations](https://capawesome.io/docs/sdks/capacitor/managed-configurations/): Access managed configuration settings deployed by an MDM channel, the counterpart to Intune's MAM channel.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/intune/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/intune/LICENSE).

## Third-Party Notices

The Microsoft Intune App SDKs for Android and iOS are proprietary software, licensed by Microsoft under the [Microsoft License Terms Intune App SDK](https://github.com/msintuneappsdk/ms-intune-app-sdk-ios/blob/master/Microsoft%20License%20Terms%20Intune%20App%20SDK%20for%20iOS.pdf). This plugin does **not** bundle or modify the Intune App SDKs — it declares them as dependencies and downloads them from Microsoft's official repositories at build or install time. By building an app with this plugin, you accept Microsoft's license terms for the Intune App SDK. The Microsoft Authentication Library (MSAL) is licensed under the MIT license. Using the plugin requires a Microsoft Intune tenant with appropriate licenses. The MIT license of this plugin covers the wrapper code only, not the Microsoft SDKs.

Note that Microsoft's license terms also place obligations on **your app** as the distributor of the Intune App SDK binaries — among other things regarding your app's own functionality and copyright notice, license compatibility, and indemnification. Review the license terms linked above before shipping your app.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Microsoft Corporation or any of its affiliates or subsidiaries. "Microsoft" and "Microsoft Intune" are trademarks of the Microsoft group of companies. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Keep Awake Plugin

Capacitor plugin to keep the screen awake.

## Features

- 🌙 **Keep awake**: Prevent the screen from dimming or turning off.
- 💤 **Allow sleep**: Restore the default screen sleep behavior at any time.
- 🔍 **State**: Read whether the screen is currently kept awake.
- 🌐 **Cross-platform**: Supports Android, iOS and Web (via the Screen Wake Lock API).
- 🤝 **Compatibility**: Works alongside the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/), [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/) and [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Keep Awake plugin is typically used whenever the screen must stay visible without user interaction, for example:

- **Media playback**: Keep the screen on while users watch videos or follow along with content.
- **Navigation and tracking**: Prevent the display from turning off during turn-by-turn navigation or workout tracking.
- **Hands-free reading**: Keep recipes, sheet music, or step-by-step instructions visible while the user's hands are busy.
- **Dashboards and kiosks**: Display live data or presentations without the screen dimming or sleeping.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-keep-awake` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-keep-awake
npx cap sync
```

This plugin is available on **Android**, **iOS** and **Web**. No additional permissions or configuration are required.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to keep the screen awake, allow it to sleep again, check whether it is currently kept awake, and check whether the feature is available.

### Keep the screen awake

Prevent the screen from dimming or turning off. The screen is kept awake until `allowSleep(...)` is called or the app is restarted. This only affects your app and is not a system-wide setting:

```
import { KeepAwake } from '@capawesome/capacitor-keep-awake';

const keepAwake = async () => {
  await KeepAwake.keepAwake();
};
```

### Allow the screen to sleep again

Restore the default screen sleep behavior at any time:

```
import { KeepAwake } from '@capawesome/capacitor-keep-awake';

const allowSleep = async () => {
  await KeepAwake.allowSleep();
};
```

### Check if the screen is kept awake

Read whether the screen is currently kept awake:

```
import { KeepAwake } from '@capawesome/capacitor-keep-awake';

const isKeptAwake = async () => {
  const { keptAwake } = await KeepAwake.isKeptAwake();
  return keptAwake;
};
```

### Check if the feature is available

On the Web, keeping the screen awake depends on whether the browser supports the [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API). On Android and iOS, this always returns `true`:

```
import { KeepAwake } from '@capawesome/capacitor-keep-awake';

const isAvailable = async () => {
  const { available } = await KeepAwake.isAvailable();
  return available;
};
```

## API

- [`allowSleep()`](#allowsleep)
- [`isAvailable()`](#isavailable)
- [`isKeptAwake()`](#iskeptawake)
- [`keepAwake()`](#keepawake)
- [Interfaces](#interfaces)

### allowSleep()

```
allowSleep() => Promise<void>
```

Allow the screen to dim or turn off again.

This reverses the effect of `keepAwake(...)`.

Only available on Android, iOS and Web.

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if keeping the screen awake is available on this device.

On Web, this depends on whether the browser supports the [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API). On Android and iOS, this always returns `true`.

Only available on Android, iOS and Web.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### isKeptAwake()

```
isKeptAwake() => Promise<IsKeptAwakeResult>
```

Check if the screen is currently kept awake.

Only available on Android, iOS and Web.

**Returns:** `Promise<IsKeptAwakeResult>`

**Since:** 0.1.0

______________________________________________________________________

### keepAwake()

```
keepAwake() => Promise<void>
```

Keep the screen awake by preventing it from dimming or turning off.

The screen is kept awake until `allowSleep(...)` is called or the app is restarted. This setting only affects your app and is not system-wide.

Only available on Android, iOS and Web.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IsAvailableResult

| Prop            | Type      | Description                                                          | Since |
| --------------- | --------- | -------------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether keeping the screen awake is available on this device or not. | 0.1.0 |

#### IsKeptAwakeResult

| Prop            | Type      | Description                                        | Since |
| --------------- | --------- | -------------------------------------------------- | ----- |
| **`keptAwake`** | `boolean` | Whether the screen is currently kept awake or not. | 0.1.0 |

## Behavior

Keep the following in mind when using this plugin:

- **App scope**: Keeping the screen awake only affects your app and is not a system-wide setting.
- **State reset**: The screen is only kept awake until `allowSleep(...)` is called or the app is restarted.
- **Web auto-release**: On the Web, the underlying [Screen Wake Lock](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) is automatically released by the browser whenever the tab becomes hidden (for example, when the user switches tabs or minimizes the window). The plugin automatically re-acquires the wake lock once the tab becomes visible again, as long as `allowSleep(...)` has not been called in the meantime.

## FAQ

### How is this plugin different from other similar plugins?

It keeps the screen awake on Android, iOS, and the Web from one fully typed API, and lets you check both whether the feature is available and whether the screen is currently kept awake. On the Web it uses the Screen Wake Lock API and automatically re-acquires the lock when a hidden tab becomes visible again, so the behavior stays predictable across platforms. It needs no permissions or configuration and is actively maintained against the latest Capacitor version.

### Which platforms does this plugin support?

The plugin supports Android, iOS and Web. On the Web, it relies on the Screen Wake Lock API, so availability depends on the browser. You can check this at runtime with the `isAvailable()` method, which always returns `true` on Android and iOS.

### Does keeping the screen awake affect other apps?

No, keeping the screen awake only affects your app and is not a system-wide setting. As soon as the user leaves your app, the default screen sleep behavior of the device applies again.

### How long is the screen kept awake?

The screen is kept awake until `allowSleep(...)` is called or the app is restarted. The setting is not persisted across app restarts.

### Why does the screen sleep again on the Web after switching tabs?

On the Web, the browser automatically releases the underlying wake lock whenever the tab becomes hidden, for example when the user switches tabs or minimizes the window. The plugin automatically re-acquires the wake lock once the tab becomes visible again, as long as `allowSleep(...)` has not been called in the meantime. See the [Behavior](#behavior) section for details.

### Do I need any permissions or configuration?

No, the plugin does not require any permissions or configuration on any platform. Simply install it and call `keepAwake()`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/): Access battery information of the device.
- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/): Read and control the screen brightness.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/keep-awake/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/keep-awake/LICENSE).

# Capacitor libSQL Plugin

Capacitor plugin for [libSQL](https://docs.turso.tech/libsql) databases.[1](#fn:1)

## Use Cases

The libSQL plugin is typically used whenever an app needs a SQL database, for example:

- **Offline-first apps**: Store data in a local database file on the device and synchronize it with a remote server using the `sync(...)` method.
- **Remote databases**: Connect directly to a remote libSQL database, such as one hosted on Turso, using a URL and authentication token.
- **Structured local storage**: Create tables and insert, update, delete, and query data with SQL statements and bound values.
- **Atomic operations**: Group multiple statements into a transaction that can be committed or rolled back as a whole.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.2.x          | >=8.x.x           | Active support |
| 0.1.x          | 7.x.x             | Deprecated     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-libsql` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-libsql
npx cap sync
```

### Android

#### 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:

- `$libsqlVersion` version of `tech.turso.libsql:libsql` (default: `0.1.2`)

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

## Usage

The following examples show how to connect to local and remote databases, query data, execute insert, update, and delete statements, run statements inside a transaction, and synchronize with a remote server.

### Connect to a local database

Connect to a local database file on the device. If no file exists at the specified path, a new file is created. If neither a path nor a URL is provided, the plugin creates a new in-memory database. This method must be called before any other methods that interact with the database:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const connectToLocalDatabase = async () => {
  const { connectionId } = await Libsql.connect({
    path: 'database.db',
  });
  console.log('Connected to database with ID:', connectionId);
};
```

### Connect to a remote database

Connect to a remote libSQL database using its URL and an authentication token:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const connectToRemoteDatabase = async () => {
  const { connectionId } = await Libsql.connect({
    url: 'libsql://your-database-url.turso.io',
    authToken: 'your-auth-token',
  });
  console.log('Connected to remote database with ID:', connectionId);
};
```

### Query data

Execute a `SELECT` statement and retrieve the result set:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const query = async () => {
  const result = await Libsql.query({
    connectionId: 'my-connection-id',
    statement: 'SELECT * FROM my_table',
  });
  console.log('Query result:', result.rows);
};
```

### Insert, update, and delete data

Execute any SQL statement, including `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE`, optionally with bound values:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const execute = async () => {
  await Libsql.execute({
    connectionId: 'my-connection-id',
    statement: 'INSERT INTO my_table (column1, column2) VALUES (?, ?)',
    values: ['value1', 'value2'],
  });
  console.log('Insert executed successfully');
};
```

### Run multiple statements in a transaction

Begin a transaction, execute statements as part of it, and either commit or roll back all changes. Transactions are only available on Android:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const performTransaction = async () => {
  const { transactionId } = await Libsql.beginTransaction({
    connectionId: 'my-connection-id',
  });
  try {
    await Libsql.execute({
      connectionId: 'my-connection-id',
      statement: 'UPDATE my_table SET column1 = ? WHERE column2 = ?',
      values: ['new_value', 'value2'],
      transactionId,
    });
    await Libsql.commitTransaction({
      connectionId: 'my-connection-id',
      transactionId,
    });
    console.log('Transaction committed successfully');
  } catch (error) {
    await Libsql.rollbackTransaction({
      connectionId: 'my-connection-id',
      transactionId,
    });
    console.error('Transaction rolled back due to error:', error);
  }
};
```

### Synchronize with a remote server

Synchronize the database with the remote server:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const sync = async () => {
  await Libsql.sync({
    connectionId: 'my-connection-id',
  });
  console.log('Database synchronized successfully');
};
```

## API

- [`beginTransaction(...)`](#begintransaction)
- [`commitTransaction(...)`](#committransaction)
- [`connect(...)`](#connect)
- [`execute(...)`](#execute)
- [`executeBatch(...)`](#executebatch)
- [`query(...)`](#query)
- [`rollbackTransaction(...)`](#rollbacktransaction)
- [`sync(...)`](#sync)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### beginTransaction(...)

```
beginTransaction(options: BeginTransactionOptions) => Promise<BeginTransactionResult>
```

Begin a transaction on the specified database connection.

Only available on Android.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `BeginTransactionOptions` |

**Returns:** `Promise<BeginTransactionResult>`

**Since:** 0.0.0

______________________________________________________________________

### commitTransaction(...)

```
commitTransaction(options: CommitTransactionOptions) => Promise<void>
```

Commit the current transaction on the specified database connection.

Only available on Android.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `CommitTransactionOptions` |

**Since:** 0.0.0

______________________________________________________________________

### connect(...)

```
connect(options: ConnectOptions) => Promise<ConnectResult>
```

Connect to a database.

This method must be called before any other methods that interact with the database.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ConnectOptions` |

**Returns:** `Promise<ConnectResult>`

**Since:** 0.0.0

______________________________________________________________________

### execute(...)

```
execute(options: ExecuteOptions) => Promise<void>
```

Execute a single SQL statement on the specified database connection.

This method can be used to execute any SQL statement, including `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE`.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ExecuteOptions` |

**Since:** 0.0.0

______________________________________________________________________

### executeBatch(...)

```
executeBatch(options: ExecuteBatchOptions) => Promise<void>
```

Execute a batch of SQL statements on the specified database connection.

This method can be used to execute multiple SQL statements in a single call.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ExecuteBatchOptions` |

**Since:** 0.0.0

______________________________________________________________________

### query(...)

```
query(options: QueryOptions) => Promise<QueryResult>
```

Query the database and return the result set.

This method can be used to execute `SELECT` statements and retrieve the result set.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `QueryOptions` |

**Returns:** `Promise<QueryResult>`

**Since:** 0.0.0

______________________________________________________________________

### rollbackTransaction(...)

```
rollbackTransaction(options: RollbackTransactionOptions) => Promise<void>
```

Rollback the current transaction on the specified database connection.

This method will undo all changes made in the current transaction.

Only available on Android.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `RollbackTransactionOptions` |

**Since:** 0.0.0

______________________________________________________________________

### sync(...)

```
sync(options: SyncOptions) => Promise<void>
```

Synchronize the database with the remote server.

Available on iOS and Android.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `SyncOptions` |

**Since:** 0.0.0

______________________________________________________________________

### Interfaces

#### BeginTransactionResult

| Prop                | Type     | Description                                 | Since |
| ------------------- | -------- | ------------------------------------------- | ----- |
| **`transactionId`** | `string` | The ID of the transaction that was started. | 0.0.0 |

#### BeginTransactionOptions

| Prop               | Type     | Description                                           | Since |
| ------------------ | -------- | ----------------------------------------------------- | ----- |
| **`connectionId`** | `string` | The ID of the connection to begin the transaction on. | 0.0.0 |

#### CommitTransactionOptions

| Prop                | Type     | Description                                            | Since |
| ------------------- | -------- | ------------------------------------------------------ | ----- |
| **`connectionId`**  | `string` | The ID of the connection to commit the transaction on. | 0.0.0 |
| **`transactionId`** | `string` | The ID of the transaction to commit.                   | 0.0.0 |

#### ConnectResult

| Prop               | Type     | Description               | Since |
| ------------------ | -------- | ------------------------- | ----- |
| **`connectionId`** | `string` | The ID of the connection. | 0.0.0 |

#### ConnectOptions

| Prop            | Type     | Description                                                                                                                                                                                                               | Since |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`authToken`** | `string` | The authentication token for the database. This is required for connecting to a remote database. If the database is local (i.e., a file on the device), this can be omitted.                                              | 0.0.0 |
| **`path`**      | `string` | The path to the database file. If no path or URL is provided, the plugin will create a new in-memory database. If no file exists at the specified path, a new file will be created.                                       | 0.0.0 |
| **`url`**       | `string` | The URL of the database. This can be used to connect to a remote database. If the URL is provided, the `authToken` must also be provided. If no path or URL is provided, the plugin will create a new in-memory database. | 0.0.0 |

#### ExecuteOptions

| Prop                | Type      | Description                                                                 | Since |
| ------------------- | --------- | --------------------------------------------------------------------------- | ----- |
| **`connectionId`**  | `string`  | The ID of the connection to execute the SQL statement on.                   | 0.0.0 |
| **`statement`**     | `string`  | The SQL statement to execute.                                               | 0.0.0 |
| **`transactionId`** | `string`  | The transaction ID to use for the SQL statement. Only available on Android. | 0.0.0 |
| **`values`**        | `Value[]` | The values to bind to the SQL statement.                                    | 0.0.0 |

#### ExecuteBatchOptions

| Prop               | Type        | Description                                       | Since |
| ------------------ | ----------- | ------------------------------------------------- | ----- |
| **`connectionId`** | `string`    | The ID of the connection to execute the batch on. | 0.0.0 |
| **`statement`**    | `string[]`  | The SQL statements to execute in the batch.       | 0.0.0 |
| **`values`**       | `Value[][]` | The values to bind to the SQL statements.         | 0.0.0 |

#### QueryResult

| Prop       | Type        | Description                       | Since |
| ---------- | ----------- | --------------------------------- | ----- |
| **`rows`** | `Value[][]` | The values returned by the query. | 0.0.0 |

#### QueryOptions

| Prop                | Type      | Description                                                         | Since |
| ------------------- | --------- | ------------------------------------------------------------------- | ----- |
| **`connectionId`**  | `string`  | The ID of the connection to query.                                  | 0.0.0 |
| **`statement`**     | `string`  | The SQL statement to execute.                                       | 0.0.0 |
| **`transactionId`** | `string`  | The transaction ID to use for the query. Only available on Android. | 0.0.0 |
| **`values`**        | `Value[]` | The values to bind to the SQL statement.                            | 0.0.0 |

#### RollbackTransactionOptions

| Prop                | Type     | Description                                              | Since |
| ------------------- | -------- | -------------------------------------------------------- | ----- |
| **`connectionId`**  | `string` | The ID of the connection to rollback the transaction on. | 0.0.0 |
| **`transactionId`** | `string` | The ID of the transaction to rollback.                   | 0.0.0 |

#### SyncOptions

| Prop               | Type     | Description                       | Since |
| ------------------ | -------- | --------------------------------- | ----- |
| **`connectionId`** | `string` | The ID of the connection to sync. | 0.0.0 |

### Type Aliases

#### Value

`string | number | null`

## FAQ

### Can I use this plugin with Turso?

Yes, you can connect to a remote libSQL database hosted on [Turso](https://docs.turso.tech/libsql) by passing the database URL and an authentication token to the `connect(...)` method, as shown in the [usage example](#connect-to-a-remote-database) above.

### Do I need a remote database to use this plugin?

No, the plugin also works with purely local databases. If you pass a `path` to the `connect(...)` method, the plugin uses a database file on the device and creates it if it does not exist. If you provide neither a path nor a URL, the plugin creates a new in-memory database.

### Are transactions supported?

Yes, you can use the `beginTransaction(...)`, `commitTransaction(...)` and `rollbackTransaction(...)` methods to group multiple statements into a transaction. Note that transactions are only available on Android.

### What is the difference between the `query` and `execute` methods?

The `query(...)` method is used to execute `SELECT` statements and retrieve the result set. The `execute(...)` method is used for any other SQL statement, including `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE`, and does not return a result set. Both methods support binding values to the statement.

### How do I keep a local database in sync with a remote server?

Call the `sync(...)` method with the ID of the connection you want to synchronize. This synchronizes the database with the remote server and is available on Android and iOS.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords or tokens.
- [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/): Access SQLite databases with support for encryption, transactions, and schema migrations.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by CHISELSTRIKE INC. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Light Sensor Plugin

Capacitor plugin to read the device's ambient light sensor.

## Features

The Capacitor Light Sensor plugin provides a complete solution for ambient light measurements in Capacitor apps. Here are some of the key features:

- 🌗 **Illuminance**: Read the ambient light level in lux.
- ⚡ **Real-time measurements**: Continuous light data with event listeners.
- 🖥️ **Native**: Supports Android.
- 🤝 **Compatibility**: Works alongside the [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Light Sensor plugin is typically used to react to the lighting conditions around the device, for example:

- **Adaptive theming**: Switch between a light and dark theme based on the ambient light level.
- **Brightness control**: Combine the illuminance readings with the [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/) plugin to adjust the screen brightness.
- **Environment monitoring**: Continuously measure the light level in a room using real-time measurement events.
- **Reading comfort**: Detect dark environments and suggest a more comfortable display mode to the user.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How ambient light readings pair with the Proximity Sensor for adaptive UX.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-light-sensor` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-light-sensor
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

iOS does not provide a public API to read the ambient light sensor, so the plugin is not implemented on this platform. The closest available signal is the screen brightness, which you can read using the [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/) plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether an ambient light sensor is available, read the current light level, and receive or stop continuous measurement updates.

### Check if the light sensor is available

Check whether the device has an ambient light sensor before using the other methods. Only available on Android:

```
import { LightSensor } from '@capawesome/capacitor-light-sensor';

const isAvailable = async () => {
  const result = await LightSensor.isAvailable();
  return result.available;
};
```

### Read the current light level

Get the most recent measurement from the ambient light sensor in lux. Only available on Android:

```
import { LightSensor } from '@capawesome/capacitor-light-sensor';

const getMeasurement = async () => {
  const measurement = await LightSensor.getMeasurement();
  console.log('Illuminance: ', measurement.illuminance);
};
```

### Receive continuous measurements

Add a listener for the `measurement` event and start the measurement updates to receive real-time light data. Only available on Android:

```
import { LightSensor } from '@capawesome/capacitor-light-sensor';

const startMeasurementUpdates = async () => {
  await LightSensor.addListener('measurement', measurement => {
    console.log('Illuminance: ', measurement.illuminance);
  });
  await LightSensor.startMeasurementUpdates();
};
```

### Stop receiving measurements

Stop the measurement updates and remove the listeners when you no longer need them:

```
import { LightSensor } from '@capawesome/capacitor-light-sensor';

const stopMeasurementUpdates = async () => {
  await LightSensor.stopMeasurementUpdates();
};

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

## API

- [`getMeasurement()`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getMeasurement()

```
getMeasurement() => Promise<GetMeasurementResult>
```

Get the latest measurement.

This method returns the most recent measurement from the ambient light sensor.

Only available on Android.

**Returns:** `Promise<Measurement>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the ambient light sensor is available on the device.

Only available on Android.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Start emitting `measurement` events.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stop emitting `measurement` events.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new measurement is available.

Only available on Android.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### Measurement

| Prop              | Type     | Description                          | Since |
| ----------------- | -------- | ------------------------------------ | ----- |
| **`illuminance`** | `number` | The ambient light level in lux (lx). | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                                  | Since |
| --------------- | --------- | ------------------------------------------------------------ | ----- |
| **`available`** | `boolean` | Whether the ambient light sensor is available on the device. | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetMeasurementResult

`Measurement`

#### MeasurementEvent

`Measurement`

## FAQ

### How is this plugin different from other similar plugins?

It reads the Android ambient light sensor in lux through a fully typed API, offering both a one-time reading and continuous real-time `measurement` events, plus an availability check so you can gracefully handle devices without the sensor. It pairs naturally with the Screen Brightness plugin for adaptive theming and brightness control, and is kept current with the latest Capacitor version. If a rough light signal is enough, screen brightness may cover it; if you need true illuminance values in lux, this plugin is built for exactly that.

### Why is this plugin not available on iOS?

iOS does not provide a public API to read the ambient light sensor, so the plugin is not implemented on this platform. The closest available signal is the screen brightness, which you can read using the [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/) plugin.

### What unit are the measurements in?

The `illuminance` property of a measurement contains the ambient light level in lux (lx).

### How do I know if the device has a light sensor?

Call the `isAvailable()` method, which returns whether the ambient light sensor is available on the device. It is recommended to check this before calling the other methods.

### What is the difference between `getMeasurement` and the `measurement` event?

The `getMeasurement()` method returns the most recent measurement from the ambient light sensor as a one-time value. The `measurement` event, in combination with `startMeasurementUpdates()`, delivers continuous real-time measurements until you call `stopMeasurementUpdates()`. See the [usage examples](#usage) above.

### Do I need any permissions or configuration on Android?

No permissions are required. However, if you are using Proguard, you need to add a keep rule for the plugin classes to your `proguard-rules.pro` file, as described in the [Installation](#installation) section.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure in hectopascals (hPa).
- [Proximity Sensor](https://capawesome.io/docs/sdks/capacitor/proximity-sensor/): Read the device's proximity sensor.
- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/): Read and control the screen brightness.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/light-sensor/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/light-sensor/LICENSE).

# Capacitor Live Update Plugin

Capacitor plugin that allows you to update your app remotely in real-time without requiring users to download a new version from the app store, known as Over-the-Air (OTA) updates.

## Features

The Capacitor Live Update plugin is one of the most feature-rich Over-the-Air (OTA) update solutions for Capacitor apps. Here are some of the key features:

- 🔋 Supports **Android and iOS**
- ⚡️ **Capacitor 6/7/8** support
- 📦 **Bundle Management**: Download, set, and delete bundles.
- ☁️ **Cloud Support**: Use the [Capawesome Cloud](https://cloud.capawesome.io/) to manage your app updates.
- 📺 **Channel Support**: Set a channel for the app to manage different versions.
- 🔄 **Auto Update**: Automatically download and set the latest bundle for the app with configurable background update strategy.
- 🛟 **Rollback**: Reset the app to the default bundle if an incompatible bundle has been set.
- 🚀 **Rollout**: Gradually roll out new bundles to gather valuable feedback.
- 🔁 **Delta Updates**: Make your updates faster by only downloading changed files.
- ⚙️ **Runtime Configuration**: Update plugin configuration at runtime without rebuilding the app.
- 📡 **Update Lifecycle Events**: Track download progress, react to bundle changes, and detect reloads with auto-blocking of rolled back bundles.
- 🏠 **Self-Hosted Bundles**: Download bundles from any URL, no Capawesome Cloud dependency required.
- 🏷️ **Custom Properties**: Associate custom key-value metadata with bundles via Capawesome Cloud.
- 🔒 **Security**: Verify the authenticity and integrity of the bundle using a public key.
- ⚔️ **Battle-Tested**: Used in more than 1,000 projects to update apps on more than 20,000,000 devices.
- 🌐 **Open Source**: Licensed under the MIT License.
- 🤝 **Compatibility**: Works alongside the [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/) and [Firebase Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/) plugins.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Live Update plugin is typically used to ship changes to users without going through the app stores, for example:

- **Instant bug fixes**: Deliver critical fixes to your users in real-time without waiting for app store reviews.
- **Fast feature delivery**: Ship new web-based features as soon as they are ready by publishing a new bundle.
- **Staged rollouts**: Gradually roll out new bundles to a subset of devices to gather feedback before a full release.
- **Testing and QA channels**: Distribute preview versions to testers via dedicated channels before promoting them to production.
- **Safe releases**: Automatically roll back to the default bundle if a faulty update prevents the app from becoming ready.

## Compatibility

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

## Demo

A working example can be found here: [capawesome-team/capacitor-live-update-demo](https://github.com/capawesome-team/capacitor-live-update-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Getting Started with Capawesome Cloud Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/)
- [Capacitor Live Updates: The Complete OTA Guide](https://capawesome.io/blog/capacitor-live-updates-guide/)
- [Best Live Update Tools for Capacitor (2026)](https://capawesome.io/blog/best-ota-update-tools-for-capacitor/)
- [Capacitor Live Updates: Signing vs Encryption](https://capawesome.io/blog/capacitor-live-updates-end-to-end-encryption/)
- [Capacitor Live Updates: Reliability & Uptime](https://capawesome.io/blog/capacitor-live-updates-reliability-and-uptime/)
- [Capawesome vs. Capgo: Which Is More Reliable?](https://capawesome.io/blog/capawesome-cloud-vs-capgo-reliability/)
- [Migrating from Ionic Appflow to Capawesome Cloud](https://capawesome.io/blog/migrating-from-ionic-appflow-to-capawesome-cloud/)
- [Migrating from App Center to Capawesome Cloud](https://capawesome.io/blog/migrating-from-app-center-to-capawesome-cloud/)
- [Live Updates for Nuxt Capacitor Apps](https://capawesome.io/blog/live-updates-for-nuxt-capacitor/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-live-update` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-live-update
npx cap sync
```

### Android

#### Channel

If you are using [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels), you can set a default channel directly in your native project by adding a string resource. This allows you to tie the channel to the version code at build time.

Add the following to your app's `build.gradle` file:

```
android {
    defaultConfig {
        resValue "string", "capawesome_live_update_default_channel", "production-" + defaultConfig.versionCode
    }
}
```

#### 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:

- `$okhttp3Version` version of `com.squareup.okhttp3:okhttp` and `com.squareup.okhttp3:okhttp-brotli` (default: `5.3.2`)
- `$zip4jVersion` version of `net.lingala.zip4j:zip4j` (default: `2.11.5`)

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

### iOS

#### Channel

If you are using [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels), you can set a default channel directly in your native project by adding a key to your `Info.plist` file. This allows you to tie the channel to the build version at build time.

Add the following to your `Info.plist` file:

```
<key>CapawesomeLiveUpdateDefaultChannel</key>
<string>production-$(CURRENT_PROJECT_VERSION)</string>
```

#### Privacy manifest

Add the `NSPrivacyAccessedAPICategoryUserDefaults` dictionary key to your [Privacy Manifest](https://capacitorjs.com/docs/ios/privacy-manifest) (usually `ios/App/PrivacyInfo.xcprivacy`):

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>
```

We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278401) as the reason for accessing the [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults) API.

## Configuration

| Prop                             | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                | Default                                                                                                                                                                                                                                                                                                                       | Since    |
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **`appId`**                      | `string`  | The app ID is used to identify the app when using [Capawesome Cloud](https://capawesome.io/cloud/). This is **NOT** the same as the app identifier (e.g. `com.example.app`). This is a unique identifier generated by Capawesome Cloud (e.g. `6e351b4f-69a7-415e-a057-4567df7ffe94`).                                                                                                                                      |                                                                                                                                                                                                                                                                                                                               | 5.0.0    |
| **`autoBlockRolledBackBundles`** | `boolean` | Whether or not to automatically block bundles that have been rolled back. When enabled, the plugin will automatically block bundles that caused a rollback (up to 100 bundles). When the limit is reached, the oldest blocked bundle is unblocked. Blocked bundles will be skipped in future sync operations. **Attention**: This option has no effect if `readyTimeout` is set to `0`. Only available on Android and iOS. | `false`                                                                                                                                                                                                                                                                                                                       | 7.3.0    |
| **`autoDeleteBundles`**          | `boolean` | Whether or not to automatically delete unused bundles. When enabled, the plugin will automatically delete unused bundles after calling `ready()`.                                                                                                                                                                                                                                                                          | `false`                                                                                                                                                                                                                                                                                                                       | 5.0.0    |
| **`autoUpdateStrategy`**         | \`'none'  | 'background'\`                                                                                                                                                                                                                                                                                                                                                                                                             | The auto-update strategy for live updates. - `none`: Live updates will not be applied automatically. - `background`: Live updates will be automatically downloaded and applied in the background at app startup and when the app resumes (if the last check was more than 15 minutes ago). Only available on Android and iOS. | `'none'` |
| **`defaultChannel`**             | `string`  | The default channel of the app. This can be overridden by `setChannel()`, the `channel` parameter of `sync()`, or the native channel configuration (`CapawesomeLiveUpdateDefaultChannel` in `Info.plist` on iOS or `capawesome_live_update_default_channel` in `strings.xml` on Android).                                                                                                                                  |                                                                                                                                                                                                                                                                                                                               | 6.3.0    |
| **`httpTimeout`**                | `number`  | The timeout in milliseconds for HTTP requests.                                                                                                                                                                                                                                                                                                                                                                             | `60000`                                                                                                                                                                                                                                                                                                                       | 6.4.0    |
| **`publicKey`**                  | `string`  | The public key to verify the integrity of the bundle. The public key must be a PEM-encoded RSA public key.                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                               | 6.1.0    |
| **`readyTimeout`**               | `number`  | The timeout in milliseconds to wait for the app to be ready before resetting to the default bundle. It is strongly **recommended** to configure this option (e.g. `10000` ms) so that the plugin can roll back to the default bundle in case of problems. If configured, the plugin will wait for the app to call the `ready()` method before resetting to the default bundle. Set to `0` to disable the timeout.          | `0`                                                                                                                                                                                                                                                                                                                           | 5.0.0    |
| **`serverDomain`**               | `string`  | The API domain of the [Capawesome Cloud](https://cloud.capawesome.io) server **without** scheme or path.                                                                                                                                                                                                                                                                                                                   | `'api.cloud.capawesome.io'`                                                                                                                                                                                                                                                                                                   | 7.0.0    |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "LiveUpdate": {
      "appId": '6e351b4f-69a7-415e-a057-4567df7ffe94',
      "autoBlockRolledBackBundles": undefined,
      "autoDeleteBundles": undefined,
      "autoUpdateStrategy": 'background',
      "defaultChannel": 'production',
      "httpTimeout": undefined,
      "publicKey": '-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDodf1SD0OOn6hIlDuKBza0Ed0OqtwyVJwiyjmE9BJaZ7y8ZUfcF+SKmd0l2cDPM45XIg2tAFux5n29uoKyHwSt+6tCi5CJA5Z1/1eZruRRqABLonV77KS3HUtvOgqRLDnKSV89dYZkM++NwmzOPgIF422mvc+VukcVOBfc8/AHQIDAQAB-----END PUBLIC KEY-----',
      "readyTimeout": 10000,
      "serverDomain": 'api.cloud.capawesome.eu'
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-live-update" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: '6e351b4f-69a7-415e-a057-4567df7ffe94',
      autoBlockRolledBackBundles: undefined,
      autoDeleteBundles: undefined,
      autoUpdateStrategy: 'background',
      defaultChannel: 'production',
      httpTimeout: undefined,
      publicKey: '-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDodf1SD0OOn6hIlDuKBza0Ed0OqtwyVJwiyjmE9BJaZ7y8ZUfcF+SKmd0l2cDPM45XIg2tAFux5n29uoKyHwSt+6tCi5CJA5Z1/1eZruRRqABLonV77KS3HUtvOgqRLDnKSV89dYZkM++NwmzOPgIF422mvc+VukcVOBfc8/AHQIDAQAB-----END PUBLIC KEY-----',
      readyTimeout: 10000,
      serverDomain: 'api.cloud.capawesome.eu',
    },
  },
};

export default config;
```

## Usage

All methods are only available on Android and iOS. The following examples show how to sync with Capawesome Cloud, mark the app as ready, check for and download new bundles, switch between and manage bundles, work with channels, inspect the current and next bundle, identify devices, read the app version, and reset to the default bundle.

### Sync with Capawesome Cloud

Automatically download and set the latest bundle for the app using [Capawesome Cloud](https://cloud.capawesome.io/). Call `reload()` or restart the app to apply the changes. The `channel` option overrides the channel for this single sync call without persisting it:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const sync = async () => {
  const result = await LiveUpdate.sync({
    channel: 'production-5',
  });
  return result.nextBundleId;
};
```

### Notify the plugin that the app is ready

Call `ready()` as soon as the app is ready to use so that the plugin knows no rollback is needed. If the `readyTimeout` configuration option is set and this method is not called in time, the plugin resets the app to the default bundle:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const ready = async () => {
  const result = await LiveUpdate.ready();
  if (result.currentBundleId) {
    console.log(`The app is now using the bundle with the identifier ${result.currentBundleId}.`);
  }
  if (result.previousBundleId) {
    console.log(`The app was using the bundle with the identifier ${result.previousBundleId}.`);
  }
  if (result.rollback) {
    console.log('The app was reset to the default bundle.');
  }
};
```

### Check if a new bundle is available

Fetch the latest bundle from Capawesome Cloud and compare it with the bundle that is currently in use:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const fetchLatestBundle = async () => {
  await LiveUpdate.fetchLatestBundle();
};

const isNewBundleAvailable = async () => {
  const { bundleId: latestBundleId } = await LiveUpdate.fetchLatestBundle({
    channel: 'production-5',
  });
  if (latestBundleId) {
    const { bundleId: currentBundleId } = await LiveUpdate.getCurrentBundle();
    return latestBundleId !== currentBundleId;
  } else {
    return false;
  }
};
```

### Download a bundle from your own server

Download a self-hosted bundle from any URL, without any Capawesome Cloud dependency:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const downloadBundle = async () => {
  await LiveUpdate.downloadBundle({ url: 'https://example.com/1.0.0.zip', bundleId: '1.0.0' });
};
```

### Switch to a downloaded bundle

Set the next bundle to use for the app. Call `reload()` or restart the app to apply the changes:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({ bundleId: '7f0b9bf2-dff6-4be2-bcac-b068cc5ea756' });
};

const reload = async () => {
  await LiveUpdate.reload();
};
```

### Manage downloaded bundles

Get the identifiers of all bundles that have been downloaded and delete bundles that are no longer needed:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const getBundles = async () => {
  const result = await LiveUpdate.getBundles();
  return result.bundleIds;
};

const deleteBundle = async () => {
  await LiveUpdate.deleteBundle({ bundleId: 'my-bundle' });
};
```

### Work with channels

Set the channel to use for updates, read the currently resolved channel, and fetch the available channels from Capawesome Cloud. The channel set via `setChannel(...)` is persisted across app restarts. Note that `fetchChannels(...)` only works for apps with public channels enabled:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const setChannel = async () => {
  await LiveUpdate.setChannel({ channel: 'production-5' });
};

const getChannel = async () => {
  const result = await LiveUpdate.getChannel();
  return result.channel;
};

const fetchChannels = async () => {
  const result = await LiveUpdate.fetchChannels();
  return result.channels;
};
```

### Inspect the current and next bundle

Get the identifier of the bundle that is currently used by the app and of the bundle that will be used after the next reload or app restart:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const getCurrentBundle = async () => {
  const result = await LiveUpdate.getCurrentBundle();
  return result.bundleId;
};

const getNextBundle = async () => {
  const result = await LiveUpdate.getNextBundle();
  return result.bundleId;
};
```

### Identify devices

Read the unique device identifier and manage a custom identifier for the device:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const getDeviceId = async () => {
  const result = await LiveUpdate.getDeviceId();
  return result.deviceId;
};

const setCustomId = async () => {
  await LiveUpdate.setCustomId({ customId: 'my-custom-id' });
};

const getCustomId = async () => {
  const result = await LiveUpdate.getCustomId();
  return result.customId;
};
```

### Read the app version

Get the native version code and version name of the app, for example to restrict live updates to compatible native versions:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const getVersionCode = async () => {
  const result = await LiveUpdate.getVersionCode();
  return result.versionCode;
};

const getVersionName = async () => {
  const result = await LiveUpdate.getVersionName();
  return result.versionName;
};
```

### Reset to the default bundle

Reset the app to the bundle that shipped with the native app binary. Call `reload()` or restart the app to apply the changes:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const reset = async () => {
  await LiveUpdate.reset();
};
```

## API

- [`clearBlockedBundles()`](#clearblockedbundles)
- [`deleteBundle(...)`](#deletebundle)
- [`downloadBundle(...)`](#downloadbundle)
- [`fetchChannels(...)`](#fetchchannels)
- [`fetchLatestBundle(...)`](#fetchlatestbundle)
- [`getBlockedBundles()`](#getblockedbundles)
- [`getBundles()`](#getbundles)
- [`getChannel()`](#getchannel)
- [`getConfig()`](#getconfig)
- [`getDownloadedBundles()`](#getdownloadedbundles)
- [`getCurrentBundle()`](#getcurrentbundle)
- [`getCustomId()`](#getcustomid)
- [`getDeviceId()`](#getdeviceid)
- [`isSyncing()`](#issyncing)
- [`getNextBundle()`](#getnextbundle)
- [`getVersionCode()`](#getversioncode)
- [`getVersionName()`](#getversionname)
- [`ready()`](#ready)
- [`reload()`](#reload)
- [`reset()`](#reset)
- [`resetConfig()`](#resetconfig)
- [`setChannel(...)`](#setchannel)
- [`setConfig(...)`](#setconfig)
- [`setCustomId(...)`](#setcustomid)
- [`setNextBundle(...)`](#setnextbundle)
- [`sync(...)`](#sync)
- [`addListener('downloadBundleProgress', ...)`](#addlistenerdownloadbundleprogress-)
- [`addListener('nextBundleSet', ...)`](#addlistenernextbundleset-)
- [`addListener('reloaded', ...)`](#addlistenerreloaded-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### clearBlockedBundles()

```
clearBlockedBundles() => Promise<void>
```

Clear all blocked bundles from the blocked list.

This removes all bundle identifiers that were automatically blocked due to rollbacks when `autoBlockRolledBackBundles` is enabled.

Only available on Android and iOS.

**Since:** 7.4.0

______________________________________________________________________

### deleteBundle(...)

```
deleteBundle(options: DeleteBundleOptions) => Promise<void>
```

Delete a bundle from the app.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `DeleteBundleOptions` |

**Since:** 5.0.0

______________________________________________________________________

### downloadBundle(...)

```
downloadBundle(options: DownloadBundleOptions) => Promise<void>
```

Download a bundle.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `DownloadBundleOptions` |

**Since:** 5.0.0

______________________________________________________________________

### fetchChannels(...)

```
fetchChannels(options?: FetchChannelsOptions | undefined) => Promise<FetchChannelsResult>
```

Fetch channels from [Capawesome Cloud](https://capawesome.io/cloud/).

This is primarily intended for development and QA purposes. It allows you to retrieve a list of available channels so you can dynamically switch between them using `setChannel(...)`.

**Attention**: Only works for apps with public channels enabled. If channels are private, they can still be set using `setChannel(...)` but won't be returned by this method.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `FetchChannelsOptions` |

**Returns:** `Promise<FetchChannelsResult>`

**Since:** 8.2.0

______________________________________________________________________

### fetchLatestBundle(...)

```
fetchLatestBundle(options?: FetchLatestBundleOptions | undefined) => Promise<FetchLatestBundleResult>
```

Fetch the latest bundle using the [Capawesome Cloud](https://capawesome.io/cloud/).

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `FetchLatestBundleOptions` |

**Returns:** `Promise<FetchLatestBundleResult>`

**Since:** 6.6.0

______________________________________________________________________

### getBlockedBundles()

```
getBlockedBundles() => Promise<GetBlockedBundlesResult>
```

Get all blocked bundle identifiers.

Returns the list of bundle identifiers that were automatically blocked due to rollbacks when `autoBlockRolledBackBundles` is enabled.

Only available on Android and iOS.

**Returns:** `Promise<GetBlockedBundlesResult>`

**Since:** 7.4.0

______________________________________________________________________

### getBundles()

```
getBundles() => Promise<GetBundlesResult>
```

Get all identifiers of bundles that have been downloaded.

Only available on Android and iOS.

**Returns:** `Promise<GetBundlesResult>`

**Since:** 5.0.0

______________________________________________________________________

### getChannel()

```
getChannel() => Promise<GetChannelResult>
```

Get the channel that is used for the update.

The channel is resolved in the following order (highest priority first):

1. `setChannel()` (SharedPreferences on Android / UserDefaults on iOS)
1. Native config (`CapawesomeLiveUpdateDefaultChannel` in `Info.plist` on iOS or `capawesome_live_update_default_channel` in `strings.xml` on Android)
1. Capacitor config `defaultChannel`

**Note**: The `channel` parameter of `sync()` takes the highest priority but is not persisted and therefore not returned by this method.

Only available on Android and iOS.

**Returns:** `Promise<GetChannelResult>`

**Since:** 5.0.0

______________________________________________________________________

### getConfig()

```
getConfig() => Promise<GetConfigResult>
```

Get the runtime configuration.

Returns the current plugin configuration including any runtime overrides set via `setConfig()`.

Only available on Android and iOS.

**Returns:** `Promise<GetConfigResult>`

**Since:** 7.4.0

______________________________________________________________________

### getDownloadedBundles()

```
getDownloadedBundles() => Promise<GetDownloadedBundlesResult>
```

Get all identifiers of bundles that have been downloaded.

Only available on Android and iOS.

**Returns:** `Promise<GetDownloadedBundlesResult>`

**Since:** 7.4.0

______________________________________________________________________

### getCurrentBundle()

```
getCurrentBundle() => Promise<GetCurrentBundleResult>
```

Get the bundle identifier of the current bundle. The current bundle is the bundle that is currently used by the app.

Only available on Android and iOS.

**Returns:** `Promise<GetCurrentBundleResult>`

**Since:** 6.7.0

______________________________________________________________________

### getCustomId()

```
getCustomId() => Promise<GetCustomIdResult>
```

Get the custom identifier of the device.

Only available on Android and iOS.

**Returns:** `Promise<GetCustomIdResult>`

**Since:** 5.0.0

______________________________________________________________________

### getDeviceId()

```
getDeviceId() => Promise<GetDeviceIdResult>
```

Get the unique device identifier.

Only available on Android and iOS.

**Returns:** `Promise<GetDeviceIdResult>`

**Since:** 5.0.0

______________________________________________________________________

### isSyncing()

```
isSyncing() => Promise<IsSyncingResult>
```

Check whether a sync operation is currently in progress.

Only available on Android and iOS.

**Returns:** `Promise<IsSyncingResult>`

**Since:** 7.4.0

______________________________________________________________________

### getNextBundle()

```
getNextBundle() => Promise<GetNextBundleResult>
```

Get the bundle identifier of the next bundle. The next bundle is the bundle that will be used after calling `reload()` or restarting the app.

Only available on Android and iOS.

**Returns:** `Promise<GetNextBundleResult>`

**Since:** 6.7.0

______________________________________________________________________

### getVersionCode()

```
getVersionCode() => Promise<GetVersionCodeResult>
```

Get the version code of the app.

On **Android**, this is the `versionCode` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file.

Only available on Android and iOS.

**Returns:** `Promise<GetVersionCodeResult>`

**Since:** 5.0.0

______________________________________________________________________

### getVersionName()

```
getVersionName() => Promise<GetVersionNameResult>
```

Get the version name of the app.

On **Android**, this is the `versionName` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file.

Only available on Android and iOS.

**Returns:** `Promise<GetVersionNameResult>`

**Since:** 5.0.0

______________________________________________________________________

### ready()

```
ready() => Promise<ReadyResult>
```

Notify the plugin that the app is ready to use and no rollback is needed.

**Attention**: This method should be called as soon as the app is ready to use to prevent the app from being reset to the default bundle. It must always be called before `sync(...)` or any other method that changes the bundle.

Only available on Android and iOS.

**Returns:** `Promise<ReadyResult>`

**Since:** 5.0.0

______________________________________________________________________

### reload()

```
reload() => Promise<void>
```

Reload the app to apply the new bundle.

This method reloads the web view only, the native process is **not** restarted. Resources of the web layer that hold an exclusive lock (e.g. IndexedDB or WebSockets) are therefore not released automatically and may prevent the new bundle from starting. Release these resources before calling this method or apply the new bundle on the next app start instead.

**Attention**: The in-memory state of the app (e.g. unsaved user input) is lost.

Only available on Android and iOS.

**Since:** 5.0.0

______________________________________________________________________

### reset()

```
reset() => Promise<void>
```

Reset the app to the default bundle.

Call `reload()` or restart the app to apply the changes.

Only available on Android and iOS.

**Since:** 5.0.0

______________________________________________________________________

### resetConfig()

```
resetConfig() => Promise<void>
```

Reset the runtime configuration to the values from the Capacitor config file.

This clears any runtime configuration set via `setConfig()`. The changes take effect immediately.

Only available on Android and iOS.

**Since:** 7.4.0

______________________________________________________________________

### setChannel(...)

```
setChannel(options: SetChannelOptions) => Promise<void>
```

Set the channel to use for the update.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetChannelOptions` |

**Since:** 5.0.0

______________________________________________________________________

### setConfig(...)

```
setConfig(options: SetConfigOptions) => Promise<void>
```

Set the runtime configuration.

This allows updating plugin configuration options at runtime. The changes are persisted across app restarts and take effect immediately.

**Important:** Runtime configuration is automatically reset to default values whenever the native app is updated to a new version. This ensures that configuration from previous versions doesn't persist after an app update.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetConfigOptions` |

**Since:** 7.4.0

______________________________________________________________________

### setCustomId(...)

```
setCustomId(options: SetCustomIdOptions) => Promise<void>
```

Set the custom identifier of the device.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetCustomIdOptions` |

**Since:** 5.0.0

______________________________________________________________________

### setNextBundle(...)

```
setNextBundle(options: SetNextBundleOptions) => Promise<void>
```

Set the next bundle to use for the app.

Call `reload()` or restart the app to apply the changes.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetNextBundleOptions` |

**Since:** 6.7.0

______________________________________________________________________

### sync(...)

```
sync(options?: SyncOptions | undefined) => Promise<SyncResult>
```

Automatically download and set the latest bundle for the app using the [Capawesome Cloud](https://capawesome.io/cloud/).

Call `reload()` or restart the app to apply the changes.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `SyncOptions` |

**Returns:** `Promise<SyncResult>`

**Since:** 5.0.0

______________________________________________________________________

### addListener('downloadBundleProgress', ...)

```
addListener(eventName: 'downloadBundleProgress', listenerFunc: DownloadBundleProgressListener) => Promise<PluginListenerHandle>
```

Listen for the download progress of a bundle.

Only available on Android and iOS.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'downloadBundleProgress'`       |
| **`listenerFunc`** | `DownloadBundleProgressListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.0.0

______________________________________________________________________

### addListener('nextBundleSet', ...)

```
addListener(eventName: 'nextBundleSet', listenerFunc: NextBundleSetListener) => Promise<PluginListenerHandle>
```

Listen for when a bundle is set as the next bundle.

This event is triggered whenever a bundle is set to be used on the next app restart, either through automatic updates or manual calls to `setNextBundle()`.

Only available on Android and iOS.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'nextBundleSet'`       |
| **`listenerFunc`** | `NextBundleSetListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.3.0

______________________________________________________________________

### addListener('reloaded', ...)

```
addListener(eventName: 'reloaded', listenerFunc: ReloadedListener) => Promise<PluginListenerHandle>
```

Listen for when the app is reloaded.

This event is triggered after the `reload()` method is called and the app has been reloaded.

**Note:** To verify whether an update was successfully applied after a reload, use the `ready()` method instead. The `ready()` method provides detailed information about the current bundle, previous bundle, and whether a rollback occurred.

Only available on Android and iOS.

| Param              | Type               |
| ------------------ | ------------------ |
| **`eventName`**    | `'reloaded'`       |
| **`listenerFunc`** | `ReloadedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.4.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 7.2.0

______________________________________________________________________

### Interfaces

#### DeleteBundleOptions

| Prop           | Type     | Description                                    | Since |
| -------------- | -------- | ---------------------------------------------- | ----- |
| **`bundleId`** | `string` | The unique identifier of the bundle to delete. | 5.0.0 |

#### DownloadBundleOptions

| Prop               | Type         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Default                          | Since   |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------- |
| **`artifactType`** | \`'manifest' | 'zip'\`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The artifact type of the bundle. | `'zip'` |
| **`bundleId`**     | `string`     | The unique identifier of the bundle. **Attention**: The value `public` is reserved and cannot be used as a bundle identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                  | 5.0.0   |
| **`checksum`**     | `string`     | The checksum of the self-hosted bundle as a SHA-256 hash in hex format to verify the integrity of the bundle. **Attention**: Only supported for the `zip` artifact type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                  | 7.1.0   |
| **`signature`**    | `string`     | The signature of the self-hosted bundle as a signed SHA-256 hash in base64 format to verify the integrity of the bundle. **Attention**: Only supported for the `zip` artifact type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                  | 7.1.0   |
| **`url`**          | `string`     | The URL of the bundle to download. For the `zip` artifact type, the URL must point to a ZIP file. For the `manifest` artifact type, the URL serves as the base URL to download the individual files. For example, if the URL is `https://example.com/download`, the plugin will download the file with the href `index.html` from `https://example.com/download?href=index.html`. To **verify the integrity** of the file, the server should return a `X-Checksum` header with the SHA-256 hash in hex format. To **verify the signature** of the file, the server should return a `X-Signature` header with the signed SHA-256 hash in base64 format. |                                  | 5.0.0   |

#### FetchChannelsResult

| Prop           | Type        | Description           | Since |
| -------------- | ----------- | --------------------- | ----- |
| **`channels`** | `Channel[]` | The list of channels. | 8.2.0 |

#### Channel

| Prop       | Type     | Description                           | Since |
| ---------- | -------- | ------------------------------------- | ----- |
| **`id`**   | `string` | The unique identifier of the channel. | 8.2.0 |
| **`name`** | `string` | The name of the channel.              | 8.2.0 |

#### FetchChannelsOptions

| Prop         | Type     | Description                               | Default | Since |
| ------------ | -------- | ----------------------------------------- | ------- | ----- |
| **`limit`**  | `number` | The maximum number of channels to return. | `50`    | 8.2.0 |
| **`offset`** | `number` | The number of channels to skip.           | `0`     | 8.2.0 |
| **`query`**  | `string` | The query to filter channels by name.     |         | 8.2.0 |

#### FetchLatestBundleResult

| Prop                   | Type                         | Description                                                                                                                                                                                     | Since                                                                                                                                         |
| ---------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **`artifactType`**     | \`'manifest'                 | 'zip'\`                                                                                                                                                                                         | The artifact type of the bundle.                                                                                                              |
| **`bundleId`**         | \`string                     | null\`                                                                                                                                                                                          | The unique identifier of the latest bundle. On Capawesome Cloud, this is the ID of the app build artifact. If `null`, no bundle is available. |
| **`channel`**          | `string`                     | The name of the channel that the bundle is actually from. This is the resolved channel after applying any forced channel assignment and may differ from the channel set by the Live Update SDK. | 8.3.0                                                                                                                                         |
| **`checksum`**         | `string`                     | The checksum of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the checksum will be returned as response header when downloading the bundle.      | 7.1.0                                                                                                                                         |
| **`customProperties`** | `{ [key: string]: string; }` | Custom properties that are associated with the latest bundle.                                                                                                                                   | 7.0.0                                                                                                                                         |
| **`downloadUrl`**      | `string`                     | The URL of the latest bundle to download. Pass this URL to the `downloadBundle(...)` method to download the bundle.                                                                             | 6.7.0                                                                                                                                         |
| **`signature`**        | `string`                     | The signature of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the signature will be returned as response header when downloading the bundle.    | 7.1.0                                                                                                                                         |

#### FetchLatestBundleOptions

| Prop          | Type     | Description                                                                                                                                                                                            | Since |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`channel`** | `string` | The preferred channel name from which the latest bundle should be fetched. This is the SDK preference and may be overridden by a forced channel assignment configured in the Capawesome Cloud Console. | 6.7.0 |

#### GetBlockedBundlesResult

| Prop            | Type       | Description                                            | Since |
| --------------- | ---------- | ------------------------------------------------------ | ----- |
| **`bundleIds`** | `string[]` | An array of unique identifiers of all blocked bundles. | 7.4.0 |

#### GetBundlesResult

| Prop            | Type       | Description                                              | Since |
| --------------- | ---------- | -------------------------------------------------------- | ----- |
| **`bundleIds`** | `string[]` | An array of unique identifiers of all available bundles. | 5.0.0 |

#### GetChannelResult

| Prop          | Type     | Description | Since                                                              |
| ------------- | -------- | ----------- | ------------------------------------------------------------------ |
| **`channel`** | \`string | null\`      | The channel name. If `null`, the app is using the default channel. |

#### GetConfigResult

| Prop                     | Type     | Description    | Since                                                                    |
| ------------------------ | -------- | -------------- | ------------------------------------------------------------------------ |
| **`appId`**              | \`string | null\`         | The app ID used to identify the app. If `null`, no app ID is configured. |
| **`autoUpdateStrategy`** | \`'none' | 'background'\` | The auto-update strategy for live updates.                               |

#### GetDownloadedBundlesResult

| Prop            | Type       | Description                                               | Since |
| --------------- | ---------- | --------------------------------------------------------- | ----- |
| **`bundleIds`** | `string[]` | An array of unique identifiers of all downloaded bundles. | 7.4.0 |

#### GetCurrentBundleResult

| Prop           | Type     | Description | Since                                                                                     |
| -------------- | -------- | ----------- | ----------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the current bundle. If `null`, the default bundle is being used. |

#### GetCustomIdResult

| Prop           | Type     | Description | Since                                                                        |
| -------------- | -------- | ----------- | ---------------------------------------------------------------------------- |
| **`customId`** | \`string | null\`      | The custom identifier of the device. If `null`, no custom identifier is set. |

#### GetDeviceIdResult

| Prop           | Type     | Description                                                                                                                                                                                                                                                                    | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`deviceId`** | `string` | The unique identifier of the device. On iOS, [`identifierForVendor`](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) is used. The value of this property is the same for apps that come from the same vendor running on the same device. | 5.0.0 |

#### IsSyncingResult

| Prop          | Type      | Description                                        | Since |
| ------------- | --------- | -------------------------------------------------- | ----- |
| **`syncing`** | `boolean` | Whether a sync operation is currently in progress. | 7.4.0 |

#### GetNextBundleResult

| Prop           | Type     | Description | Since                                                                                  |
| -------------- | -------- | ----------- | -------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the next bundle. If `null`, the default bundle is being used. |

#### GetVersionCodeResult

| Prop              | Type     | Description                                                                                                                                                                            | Since |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`versionCode`** | `string` | The version code of the app. On **Android**, this is the `versionCode` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file. | 5.0.0 |

#### GetVersionNameResult

| Prop              | Type     | Description                                                                                                                                                                                       | Since |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`versionName`** | `string` | The version name of the app. On **Android**, this is the `versionName` from the `android/app/build.gradle` file. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file. | 5.0.0 |

#### ReadyResult

| Prop                   | Type      | Description                                             | Since                                                                                   |
| ---------------------- | --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **`previousBundleId`** | \`string  | null\`                                                  | The identifier of the previous bundle used. If `null`, the default bundle was used.     |
| **`currentBundleId`**  | \`string  | null\`                                                  | The identifier of the current bundle used. If `null`, the default bundle is being used. |
| **`rollback`**         | `boolean` | Whether or not the app was reset to the default bundle. | 7.0.0                                                                                   |

#### SetChannelOptions

| Prop          | Type     | Description | Since                                               |
| ------------- | -------- | ----------- | --------------------------------------------------- |
| **`channel`** | \`string | null\`      | The channel name. Set `null` to remove the channel. |

#### SetConfigOptions

| Prop        | Type     | Description | Since                                                                                                 |
| ----------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| **`appId`** | \`string | null\`      | The app ID used to identify the app. Set `null` to reset to the value from the Capacitor config file. |

#### SetCustomIdOptions

| Prop           | Type     | Description | Since                                                                            |
| -------------- | -------- | ----------- | -------------------------------------------------------------------------------- |
| **`customId`** | \`string | null\`      | The custom identifier of the device. Set `null` to remove the custom identifier. |

#### SetNextBundleOptions

| Prop           | Type     | Description | Since                                                                                                         |
| -------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the bundle to use. Set `null` to use the default bundle (same as calling `reset()`). |

#### SyncResult

| Prop               | Type     | Description | Since                                                                                                      |
| ------------------ | -------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| **`nextBundleId`** | \`string | null\`      | The identifier of the next bundle to use. If `null`, the app is up-to-date and no new bundle is available. |

#### SyncOptions

| Prop          | Type     | Description                                                                                                                                                                                            | Since |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`channel`** | `string` | The preferred channel name from which the latest bundle should be fetched. This is the SDK preference and may be overridden by a forced channel assignment configured in the Capawesome Cloud Console. | 6.7.0 |

#### PluginListenerHandle

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

#### DownloadBundleProgressEvent

Event that is triggered when the download progress of a bundle changes.

| Prop                  | Type     | Description                                                             | Since |
| --------------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`bundleId`**        | `string` | The unique identifier of the bundle that is being downloaded.           | 7.0.0 |
| **`downloadedBytes`** | `number` | The number of bytes that have been downloaded.                          | 7.0.0 |
| **`progress`**        | `number` | The progress of the download in percent as a value between `0` and `1`. | 7.0.0 |
| **`totalBytes`**      | `number` | The total number of bytes to download.                                  | 7.0.0 |

#### NextBundleSetEvent

Event that is triggered when a bundle is set as the next bundle.

| Prop           | Type     | Description | Since                                                                                                           |
| -------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the bundle that is set as the next bundle. If `null`, the default bundle will be used. |

### Type Aliases

#### DownloadBundleProgressListener

Listener for the download progress of a bundle.

`(event: DownloadBundleProgressEvent): void`

#### NextBundleSetListener

Listener for when a bundle is set as the next bundle.

`(event: NextBundleSetEvent): void`

#### ReloadedListener

Listener for when the app is reloaded.

`(): void`

## Testing

When testing the plugin, you must make sure that you do not use the [Live Reload](https://ionicframework.com/docs/cli/livereload) option, as in this case a development server is used to load the bundle and not the local file system.

Therefore, simply start your app without the live reload option, for example with the following command:

```
npx ionic cap run android --open
```

If you want to **not** receive live updates to test other parts of your app, you can simply set a non-existent channel, for example:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const sync = async () => {
  await LiveUpdate.sync({ channel: 'non-existent-channel' });
};
```

This way, the app will check for updates, but no updates will be found.

### Check which bundle is running

If an update does not seem to be applied, log the identifier of the current bundle and the path that the web view is serving as early as possible at app start:

```
import { WebView } from '@capacitor/core';
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const logCurrentBundle = async () => {
  const { bundleId } = await LiveUpdate.getCurrentBundle();
  const { path } = await WebView.getServerBasePath();
  console.log(`Bundle: ${bundleId ?? 'default'} (${path})`);
};
```

Because [`reload()`](#reload) restarts the web layer, this also logs both values after a reload. If they change after the reload, the new bundle was applied and any remaining problem is in the web layer of your app (see [Why does my app hang after calling `reload()`?](#why-does-my-app-hang-after-calling-reload)).

## Limitations

Live updates are only supported for [binary-compatible changes](https://capawesome.io/docs/cloud/live-updates/faq/#what-are-binary-compatible-changes) (e.g. HTML, CSS, JavaScript). If you change native code, such as adding a new plugin, you need to resubmit your app to the app stores. For this reason, you must be careful to [restrict live updates to compatible native versions](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/) of your app.

## FAQ

### What is a bundle?

A bundle is a set of web assets (HTML, CSS, JavaScript, etc.) that make up your app's user interface. The plugin manages two types of bundles: the **built-in bundle** that ships with the native app binary, and **live update bundles** that are downloaded at runtime to update the app without a native release. Each live update bundle has a unique **bundle ID** returned by the [`fetchLatestBundle(...)`](#fetchlatestbundle) method. On Capawesome Cloud, the bundle ID corresponds to the ID of the app build artifact.

### How do I set a channel?

There are four ways to set a channel, listed from lowest to highest priority:

1. **Capacitor config**: Set the `defaultChannel` property in the [plugin configuration](#configuration). This is the simplest way to set a static default channel.
1. **Native config**: Set `CapawesomeLiveUpdateDefaultChannel` in `Info.plist` (iOS) or `capawesome_live_update_default_channel` in `strings.xml` (Android). This is useful for [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels) where the channel is tied to the build version.
1. **[`setChannel(...)`](#setchannel)**: Set the channel at runtime. The value is persisted across app restarts.
1. **[`sync(...)`](#sync)**: Pass a `channel` option to override the channel for a single sync call. This does **not** persist the channel.

Each method overrides the ones above it. You can check the currently resolved channel by calling [`getChannel()`](#getchannel).

Additionally, Capawesome Cloud supports [forced channel assignments](https://capawesome.io/blog/capawesome-cloud-forced-channel-assignments/) which allow you to override the channel for a specific device without any app code changes. Please note that forced channel assignments have a higher priority than all of the above methods and should be used with caution.

### Why can't I see my changes during development?

As soon as you have installed a live update, the app will use the live update bundle and no longer the default bundle. So if you make local changes to your app and execute `npx cap run`, for example, these changes will apply to the default bundle, which is not currently in use. You then have three options to get back to the default bundle:

1. **Reset**: Call the [`reset()`](#reset) method to reset the app to the default bundle.
1. **Reinstall**: Reinstall the app to remove the live update bundle.
1. **Update**: Increase the native version code of your app so that Capacitor automatically resets to the default bundle.

However, this is only a problem during development. It is not a problem in production, as Capacitor automatically resets to the default bundle after a native update.

### Do I have to use Capawesome Cloud?

No, the plugin also supports self-hosted bundles. You can download a bundle from any URL using the [`downloadBundle(...)`](#downloadbundle) method and apply it with [`setNextBundle(...)`](#setnextbundle), without any Capawesome Cloud dependency. Capawesome Cloud is only required for the convenience features such as [`sync(...)`](#sync), channels, and rollouts.

### What changes can I ship with a live update?

Live updates are only supported for [binary-compatible changes](https://capawesome.io/docs/cloud/live-updates/faq/#what-are-binary-compatible-changes) such as HTML, CSS, and JavaScript. If you change native code, for example by adding a new plugin, you need to resubmit your app to the app stores. You should therefore [restrict live updates to compatible native versions](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/) of your app, as described in the [Limitations](#limitations) section.

### In which order should I call `ready()` and `sync()`?

Always call [`ready()`](#ready) first, as early as possible after the app has started, and only then [`sync()`](#sync) or any other method that changes the bundle. `ready()` confirms that the current bundle works and stops the rollback timer. If you call `sync()` first, the `readyTimeout` keeps running while the next bundle is being downloaded, which can roll back a bundle that actually works.

### How does the rollback mechanism work?

If the `readyTimeout` configuration option is set, the plugin waits for the app to call the [`ready()`](#ready) method after a new bundle has been applied. If the method is not called within the configured timeout, the plugin assumes the bundle is faulty and resets the app to the default bundle. It is strongly recommended to configure `readyTimeout` (e.g. `10000` ms). Additionally, with the `autoBlockRolledBackBundles` option enabled, bundles that caused a rollback are automatically blocked and skipped in future sync operations.

### Why does my app hang after calling `reload()`?

If your app shows a blank or loading screen after calling [`reload()`](#reload) but works after a force quit, the new bundle was most likely applied correctly. You can verify this by logging the [current bundle](#check-which-bundle-is-running) at app start.

`reload()` reloads the web view without restarting the native process. Resources of the web layer that hold an exclusive lock are therefore not released automatically and can block the new bundle from starting. A force quit starts a new process and releases these resources, which is why the update seems to be applied only after a restart.

The most common cause is IndexedDB. The Firebase JS SDK, for example, holds an IndexedDB lease as long as Firestore offline persistence is enabled. Terminate the client before reloading the app:

```
import { getFirestore, terminate } from 'firebase/firestore';

await terminate(getFirestore());
await LiveUpdate.reload();
```

Keep in mind that offline persistence may be active even if you try to exclude web views, because guards that detect the browser by user agent usually also match the `WKWebView` on iOS. On Android, the problem is less likely to occur because Chromium recovers from a stale lease.

Other candidates are WebSockets, Web Locks and service workers. If you cannot release these resources, apply the new bundle on the next app start instead of reloading the app.

## Related Plugins

- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist users with native app updates, which are required for changes that are not binary-compatible.
- [Firebase Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/): Change the behavior and appearance of your app remotely without publishing an update.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/live-update/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/live-update/LICENSE).

# Capacitor LLM Plugin

Capacitor plugin for running on-device large language models (LLMs) on Android and iOS. Uses the system-provided models Apple Intelligence (Foundation Models) and Gemini Nano (AICore) with chat sessions, token streaming and cancellation.

## Features

The Capacitor LLM plugin brings the platform's own on-device AI models to your Capacitor app. Here are some of the key features:

- 🧠 **System Models**: Uses the models that ship with the operating system (Apple Intelligence on iOS, Gemini Nano on Android). No model files to bundle, no API keys, no cloud calls.
- 🔒 **Private by Design**: All inference runs on the device. Prompts and responses never leave the user's phone.
- 💬 **Chat Sessions**: Create chats with instructions (system prompt) that keep the conversation context across multiple generations.
- 🌊 **Token Streaming**: Stream the response chunk by chunk via events for a responsive UI.
- ✋ **Cancellation**: Cancel an in-flight generation at any time.
- 🚦 **Typed Availability**: Check the model availability with typed status values and get notified about changes.
- ⤵️ **Model Download**: Trigger the Gemini Nano model download on Android with progress events.
- 🔓 **Public APIs Only**: Built exclusively on public platform APIs, so it is safe for App Review and resilient to OS updates.
- 🤝 **Compatibility**: Works hand in hand with the [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The LLM plugin is typically used whenever an app needs AI text generation without sending data to a server, for example:

- **Summarization**: Summarize notes, articles or messages on the device.
- **Smart Replies**: Suggest replies for chats and emails.
- **Rewriting**: Rephrase, shorten or proofread user-written text.
- **Offline Assistants**: Build chat assistants that work without an internet connection.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor LLM Plugin](https://capawesome.io/blog/announcing-the-capacitor-llm-plugin/): Run on-device language models with Apple Intelligence on iOS and Gemini Nano on Android, fully offline.
- [How to Use Apple Intelligence in a Capacitor App](https://capawesome.io/blog/how-to-use-apple-intelligence-in-a-capacitor-app/): Gate on availability, generate and stream text, and manage the context window on iOS 26.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-llm` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-llm
npx cap sync
```

### Android

The plugin uses the [ML Kit GenAI Prompt API](https://developers.google.com/ml-kit/genai/prompt/android) to run Gemini Nano via AICore. The SDK is declared as a regular Gradle dependency and fetched from Google's Maven repository when your app is built. The model itself is managed by the system (AICore) and is **not** bundled with your app.

**Attention**:

- Gemini Nano is only available on [Gemini Nano-capable devices](https://developers.google.com/ml-kit/genai#supported_devices) (for example the Google Pixel 9 series or Samsung Galaxy S25 series) with AICore. The list of supported devices is still short, so always check `getAvailability()` at runtime and design a fallback.
- The ML Kit GenAI Prompt SDK is still in **beta**, so breaking changes in the underlying SDK are possible.
- Apps using Gemini Nano are subject to Google's [Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy).

#### Minimum SDK Version

The ML Kit GenAI Prompt SDK requires a minimum SDK version of `26`. Make sure that the `minSdkVersion` in your `android/variables.gradle` file is set to at least `26`:

```
ext {
    minSdkVersion = 26
}
```

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### Variables

If needed, you can define the following project variables in your app’s `variables.gradle` file to change the default versions of the dependencies:

- `$mlkitGenaiPromptVersion` version of `com.google.mlkit:genai-prompt` (default: `1.0.0-beta2`)
- `$kotlinVersion` version of `org.jetbrains.kotlin:kotlin-gradle-plugin` (default: `2.1.20`)
- `$kotlinxCoroutinesVersion` version of `org.jetbrains.kotlinx:kotlinx-coroutines-android` (default: `1.10.2`)

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

### iOS

The plugin uses the [Foundation Models](https://developer.apple.com/documentation/foundationmodels) framework, which is part of the operating system. No additional dependencies or configuration are required.

**Attention**:

- The Foundation Models framework requires **iOS 26 or later** on an [Apple Intelligence-enabled device](https://www.apple.com/apple-intelligence/) (iPhone 15 Pro or later) with Apple Intelligence turned on. On older iOS versions, all methods except `getAvailability()` reject as unavailable.
- Building the plugin requires **Xcode 26 or later**.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check the model availability, download the model, create and delete chats, generate text, stream the response, cancel a generation, and tune the generation parameters.

### Check the model availability

The plugin uses the model that ships with the operating system, so its availability depends on the device and OS version. Always call `getAvailability()` before you generate text and handle every status. Listen for the `availabilityChange` event to be notified when the status changes:

| Status                | Meaning                                             | What you can do                                                   |
| --------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| `available`           | The model is ready to use.                          | Start generating.                                                 |
| `device-not-eligible` | The device hardware does not support the model.     | Offer a fallback (for example a cloud-based or custom model).     |
| `downloadable`        | The model can be downloaded.                        | Call `downloadModel()` to start the download.                     |
| `downloading`         | The model is currently being downloaded.            | Wait and listen for `availabilityChange` events.                  |
| `not-enabled`         | The model is disabled on the device.                | Ask the user to enable Apple Intelligence in the system settings. |
| `not-ready`           | The model is not ready yet.                         | Try again later.                                                  |
| `unavailable`         | No system model exists on this platform/OS version. | Offer a fallback or hide the feature.                             |

On Android, only `available`, `downloadable`, `downloading` and `unavailable` are reported. On iOS, only `available`, `device-not-eligible`, `not-enabled`, `not-ready` and `unavailable` are reported:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const getAvailability = async () => {
  const { status } = await Llm.getAvailability();
  return status;
};

const addAvailabilityChangeListener = async () => {
  await Llm.addListener('availabilityChange', event => {
    console.log(`Availability changed: ${event.status}`);
  });
};
```

### Download the model

If the availability status is `downloadable`, the model must be downloaded before it can be used. On Android, trigger the download explicitly and follow its progress via the `downloadProgress` event. On iOS, the download is managed by the system and cannot be triggered by the app. Only available on Android:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const downloadModel = async () => {
  const { status } = await Llm.getAvailability();
  if (status !== 'downloadable') {
    return;
  }
  await Llm.addListener('downloadProgress', event => {
    console.log(`Download progress: ${event.progress * 100}%`);
  });
  await Llm.downloadModel();
};
```

### Create and delete a chat

A chat keeps the conversation context across multiple generations and can be given instructions (system prompt) that guide the model's responses. Chats live in memory until they are deleted with `deleteChat(...)`, so delete the chats you no longer need to free the associated native resources. Only available on Android and iOS:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const createChat = async () => {
  const { id } = await Llm.createChat({
    instructions: 'You are a helpful assistant that answers briefly.',
  });
  return id;
};

const deleteChat = async (chatId: string) => {
  await Llm.deleteChat({ id: chatId });
};
```

### Generate text

Generate a response for a prompt and wait for the complete text. Only one generation can be in flight per chat at a time. Only available on Android and iOS:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const generateText = async (chatId: string) => {
  const { text } = await Llm.generateText({
    chatId,
    prompt: 'Why is the sky blue?',
  });
  return text;
};
```

### Stream the response

Stream the response chunk by chunk via the `textChunk` event for a more responsive UI. The returned promise resolves with the complete response text. Only available on Android and iOS:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const streamText = async (chatId: string) => {
  await Llm.addListener('textChunk', event => {
    if (event.chatId === chatId) {
      console.log(event.text); // Append the chunks to your UI
    }
  });
  const { text } = await Llm.streamText({
    chatId,
    prompt: 'Tell me a short story about a magical dog.',
  });
  return text; // The complete response text
};
```

### Cancel a generation

Cancel the in-flight generation of a chat. The pending promise rejects with the `GENERATION_CANCELED` error code. On iOS, the generation is canceled immediately. On Android, cancellation is best-effort, so a few more chunks may be emitted. Only available on Android and iOS:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const cancelGeneration = async (chatId: string) => {
  await Llm.cancelGeneration({ chatId });
};
```

### Tune the generation parameters

`maxOutputTokens` and `temperature` can be set per chat with `createChat(...)` and overridden per request with `generateText(...)` or `streamText(...)`. Only available on Android and iOS:

```
import { Llm } from '@capawesome-team/capacitor-llm';

const createChatWithParameters = async () => {
  const { id } = await Llm.createChat({
    maxOutputTokens: 256,
    temperature: 0.7,
  });
  const { text } = await Llm.generateText({
    chatId: id,
    prompt: 'Write a haiku about the sea.',
    temperature: 0.2, // Overrides the chat's default value
  });
  return text;
};
```

The platforms enforce different limits on the generation parameters:

| Parameter         | Android (Gemini Nano)                  | iOS (Apple Intelligence)                     |
| ----------------- | -------------------------------------- | -------------------------------------------- |
| `maxOutputTokens` | Limited to a maximum of `4096` tokens. | No documented hard limit.                    |
| `temperature`     | Must be between `0.0` and `1.0`.       | Values greater than `1.0` are allowed.       |
| Context size      | Input must be under ~4,000 tokens.     | Context window of ~4,096 tokens per session. |

If the context limit of a chat is exceeded, the generation rejects with the `GENERATION_FAILED` error code. In that case, create a new chat.

## API

- [`cancelGeneration(...)`](#cancelgeneration)
- [`createChat(...)`](#createchat)
- [`deleteChat(...)`](#deletechat)
- [`downloadModel()`](#downloadmodel)
- [`generateText(...)`](#generatetext)
- [`getAvailability()`](#getavailability)
- [`streamText(...)`](#streamtext)
- [`addListener('availabilityChange', ...)`](#addlisteneravailabilitychange-)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('textChunk', ...)`](#addlistenertextchunk-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### cancelGeneration(...)

```
cancelGeneration(options: CancelGenerationOptions) => Promise<void>
```

Cancel the in-flight text generation of a chat.

The pending `generateText(...)` or `streamText(...)` promise rejects with the `GENERATION_CANCELED` error code.

On **Android**, cancellation is best-effort. The generation is interrupted as soon as possible but a few more chunks may be emitted.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `CancelGenerationOptions` |

**Since:** 0.0.1

______________________________________________________________________

### createChat(...)

```
createChat(options?: CreateChatOptions | undefined) => Promise<CreateChatResult>
```

Create a new chat session.

A chat keeps the conversation context across multiple generations until it is deleted with `deleteChat(...)`.

If a chat with the provided identifier already exists, the promise rejects with the `CHAT_ALREADY_EXISTS` error code.

On **iOS**, each chat is backed by a native language model session that maintains the conversation context.

On **Android**, the conversation history is kept in memory by the plugin and included in each prompt since the system API does not provide native multi-turn sessions.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `CreateChatOptions` |

**Returns:** `Promise<CreateChatResult>`

**Since:** 0.0.1

______________________________________________________________________

### deleteChat(...)

```
deleteChat(options: DeleteChatOptions) => Promise<void>
```

Delete a chat session and free the associated native resources.

An in-flight generation of the chat is canceled.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DeleteChatOptions` |

**Since:** 0.0.1

______________________________________________________________________

### downloadModel()

```
downloadModel() => Promise<void>
```

Download the on-device model.

Call this method if `getAvailability()` returns the `downloadable` status. The returned promise resolves when the download is complete. The download progress is emitted via the `downloadProgress` event.

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### generateText(...)

```
generateText(options: GenerateTextOptions) => Promise<GenerateTextResult>
```

Generate text for a prompt and resolve with the complete response.

Only one generation can be in flight per chat at a time. Starting another one rejects with the `GENERATION_IN_PROGRESS` error code.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GenerateTextOptions` |

**Returns:** `Promise<GenerateTextResult>`

**Since:** 0.0.1

______________________________________________________________________

### getAvailability()

```
getAvailability() => Promise<GetAvailabilityResult>
```

Get the availability status of the on-device model.

This method never rejects. On platforms or OS versions without a system model it resolves with the `unavailable` status.

**Returns:** `Promise<GetAvailabilityResult>`

**Since:** 0.0.1

______________________________________________________________________

### streamText(...)

```
streamText(options: StreamTextOptions) => Promise<StreamTextResult>
```

Generate text for a prompt and stream the response.

Incremental chunks are emitted via the `textChunk` event while the generation is running. The returned promise resolves with the complete response text when the generation is finished.

Only one generation can be in flight per chat at a time. Starting another one rejects with the `GENERATION_IN_PROGRESS` error code.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `StreamTextOptions` |

**Returns:** `Promise<StreamTextResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('availabilityChange', ...)

```
addListener(eventName: 'availabilityChange', listenerFunc: (event: AvailabilityChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the availability status of the on-device model changes.

The plugin watches the availability status only while at least one listener for this event is attached.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'availabilityChange'`                     |
| **`listenerFunc`** | `(event: AvailabilityChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the on-device model is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('textChunk', ...)

```
addListener(eventName: 'textChunk', listenerFunc: (event: TextChunkEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new text chunk is generated during a streaming generation started with `streamText(...)`.

Only available on Android and iOS.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'textChunk'`                     |
| **`listenerFunc`** | `(event: TextChunkEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### CancelGenerationOptions

| Prop         | Type     | Description                                                               | Since |
| ------------ | -------- | ------------------------------------------------------------------------- | ----- |
| **`chatId`** | `string` | The identifier of the chat whose in-flight generation should be canceled. | 0.0.1 |

#### CreateChatResult

| Prop     | Type     | Description                                | Since |
| -------- | -------- | ------------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the created chat. | 0.0.1 |

#### CreateChatOptions

| Prop                  | Type     | Description                                                                                                                                                                                                                                          | Since |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**              | `string` | The unique identifier of the chat. If not provided, a random UUID is generated.                                                                                                                                                                      | 0.0.1 |
| **`instructions`**    | `string` | The instructions (system prompt) that guide the model's responses in this chat.                                                                                                                                                                      | 0.0.1 |
| **`maxOutputTokens`** | `number` | The default maximum number of tokens the model may generate per response in this chat. Can be overridden per request. On **Android**, the value is limited to a maximum of `4096` tokens.                                                            | 0.0.1 |
| **`temperature`**     | `number` | The default sampling temperature for responses in this chat. Higher values produce more creative results, lower values produce more deterministic results. Can be overridden per request. On **Android**, the value must be between `0.0` and `1.0`. | 0.0.1 |

#### DeleteChatOptions

| Prop     | Type     | Description                           | Since |
| -------- | -------- | ------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the chat to delete. | 0.0.1 |

#### GenerateTextResult

| Prop       | Type     | Description         | Since |
| ---------- | -------- | ------------------- | ----- |
| **`text`** | `string` | The generated text. | 0.0.1 |

#### GenerateTextOptions

| Prop                  | Type     | Description                                                                                                                                                                   | Since |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`chatId`**          | `string` | The identifier of the chat to generate the text in.                                                                                                                           | 0.0.1 |
| **`maxOutputTokens`** | `number` | The maximum number of tokens the model may generate for this request. Overrides the chat's default value. On **Android**, the value is limited to a maximum of `4096` tokens. | 0.0.1 |
| **`prompt`**          | `string` | The prompt to generate a response for.                                                                                                                                        | 0.0.1 |
| **`temperature`**     | `number` | The sampling temperature for this request. Overrides the chat's default value. On **Android**, the value must be between `0.0` and `1.0`.                                     | 0.0.1 |

#### GetAvailabilityResult

| Prop         | Type                 | Description                                     | Since |
| ------------ | -------------------- | ----------------------------------------------- | ----- |
| **`status`** | `AvailabilityStatus` | The availability status of the on-device model. | 0.0.1 |

#### StreamTextResult

| Prop       | Type     | Description                  | Since |
| ---------- | -------- | ---------------------------- | ----- |
| **`text`** | `string` | The complete generated text. | 0.0.1 |

#### StreamTextOptions

| Prop                  | Type     | Description                                                                                                                                                                   | Since |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`chatId`**          | `string` | The identifier of the chat to generate the text in.                                                                                                                           | 0.0.1 |
| **`maxOutputTokens`** | `number` | The maximum number of tokens the model may generate for this request. Overrides the chat's default value. On **Android**, the value is limited to a maximum of `4096` tokens. | 0.0.1 |
| **`prompt`**          | `string` | The prompt to generate a response for.                                                                                                                                        | 0.0.1 |
| **`temperature`**     | `number` | The sampling temperature for this request. Overrides the chat's default value. On **Android**, the value must be between `0.0` and `1.0`.                                     | 0.0.1 |

#### PluginListenerHandle

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

#### AvailabilityChangeEvent

| Prop         | Type                 | Description                                         | Since |
| ------------ | -------------------- | --------------------------------------------------- | ----- |
| **`status`** | `AvailabilityStatus` | The new availability status of the on-device model. | 0.0.1 |

#### DownloadProgressEvent

| Prop           | Type     | Description                                           | Since |
| -------------- | -------- | ----------------------------------------------------- | ----- |
| **`progress`** | `number` | The download progress as a value between `0` and `1`. | 0.0.1 |

#### TextChunkEvent

| Prop         | Type     | Description                                                                                                            | Since |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----- |
| **`chatId`** | `string` | The identifier of the chat the chunk belongs to.                                                                       | 0.0.1 |
| **`text`**   | `string` | The newly generated text chunk. Append the chunks in the order they are received to reconstruct the complete response. | 0.0.1 |

### Type Aliases

#### AvailabilityStatus

The availability status of the on-device model.

- `available`: The model is downloaded and ready to use.
- `device-not-eligible`: The device does not support the on-device model.
- `downloadable`: The model can be downloaded. On Android, call `downloadModel()` to trigger the download.
- `downloading`: The model is currently being downloaded.
- `not-enabled`: The on-device model is disabled. On iOS, the user must enable Apple Intelligence in the system settings.
- `not-ready`: The model is not ready yet, for example because the system is still preparing it. Try again later.
- `unavailable`: The model is not available on this platform or OS version.

`'available' | 'device-not-eligible' | 'downloadable' | 'downloading' | 'not-enabled' | 'not-ready' | 'unavailable'`

## FAQ

### How is this plugin different from other similar plugins?

It runs entirely on the platform's own on-device models — Apple Intelligence on iOS and Gemini Nano on Android — so prompts and responses never leave the device and there are no model files to bundle, API keys or cloud calls. You get chat sessions that keep context, token streaming, cancellation and typed availability checks through one fully typed API that is actively maintained against the latest OS and Capacitor versions, and it's backed by dedicated support. If you just need occasional cloud completions, a plain HTTP call may be enough; if you want private, offline text generation with a complete on-device workflow, this plugin is built for exactly that.

### Is text generation available on the web?

No. Browsers do not provide a system language model, so all methods except `getAvailability()` reject with an unimplemented error on the web. `getAvailability()` resolves with the `unavailable` status.

### Which devices support on-device text generation?

On iOS, all Apple Intelligence-enabled devices (iPhone 15 Pro or later) running iOS 26 or later. On Android, only [Gemini Nano-capable devices](https://developers.google.com/ml-kit/genai#supported_devices) with AICore, for example the Google Pixel 9 series or Samsung Galaxy S25 series. Always check `getAvailability()` at runtime.

### Can I use my own model files?

No. The plugin deliberately supports only the system-provided models. This keeps your app small and inference fast. Support for custom model runtimes may be added in the future.

### Why does a generation reject with `GENERATION_FAILED`?

The most common reasons are an exceeded context window (create a new chat in that case), content that is blocked by the platform's safety guardrails, or an exceeded AICore quota on Android. The error message contains the platform-specific reason.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Store chat data securely on the device.
- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/): Turn the user's voice into prompts.
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Read the generated responses aloud.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/llm/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/llm/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/llm/LICENSE).

# Capacitor Localization Plugin

Capacitor plugin to read the user's localization preferences, such as preferred locales, time zone, and regional formatting settings.

## Features

- 🌍 **Preferred locales**: Read the user's preferred locales, ordered by preference.
- 💱 **Regional formatting**: Read currency, decimal, and grouping separators per locale.
- ↔️ **Text direction**: Detect whether a locale is written left-to-right or right-to-left.
- 📏 **Measurement system**: Detect the metric, US, or UK measurement system.
- 🕐 **Settings**: Read the time zone, clock format, and first day of the week.
- 🖥️ **Cross-platform**: Full support for Android, iOS, and Web.
- 🤝 **Compatibility**: Works alongside the [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/), [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) and [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Localization plugin is typically used to adapt an app to the user's language and regional preferences, for example:

- **Localized formatting**: Format numbers and prices with the correct decimal separator, grouping separator, and currency symbol for the user's locale.
- **Right-to-left layouts**: Switch the layout direction of your app based on the text direction of the user's preferred language.
- **Unit display**: Show distances and weights in metric or imperial units depending on the user's measurement system.
- **Date and time display**: Render times in the user's time zone and clock format, and start calendar views on the correct first day of the week.
- **Language selection**: Preselect the best matching app language from the user's preferred locales.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-localization` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-localization
npx cap sync
```

No additional permissions or configuration are required on any platform.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read the user's preferred locales and their regional formatting settings.

### Get the user's preferred locales

Read the user's preferred locales, ordered by preference. The first entry is the most preferred locale. Each locale contains the language tag, region code, currency, number separators, text direction, and measurement system:

```
import { Localization } from '@capawesome/capacitor-localization';

const getLocales = async () => {
  const { locales } = await Localization.getLocales();
  return locales;
};
```

### Read the user's regional settings

Read the user's regional formatting settings, such as the time zone, whether a 24-hour clock is preferred, and the first day of the week:

```
import { Localization } from '@capawesome/capacitor-localization';

const getSettings = async () => {
  const settings = await Localization.getSettings();
  return settings;
};
```

## API

- [`getLocales()`](#getlocales)
- [`getSettings()`](#getsettings)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getLocales()

```
getLocales() => Promise<GetLocalesResult>
```

Get the user's preferred locales, ordered by preference.

The first entry is the most preferred locale.

**Returns:** `Promise<GetLocalesResult>`

**Since:** 0.1.0

______________________________________________________________________

### getSettings()

```
getSettings() => Promise<GetSettingsResult>
```

Get the user's regional formatting settings.

**Returns:** `Promise<GetSettingsResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetLocalesResult

| Prop          | Type       | Description                                                                                        | Since |
| ------------- | ---------- | -------------------------------------------------------------------------------------------------- | ----- |
| **`locales`** | `Locale[]` | The user's preferred locales, ordered by preference. The first entry is the most preferred locale. | 0.1.0 |

#### Locale

| Prop                    | Type                | Description                                     | Since                                                                                                                                       |
| ----------------------- | ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **`currencyCode`**      | \`string            | null\`                                          | The ISO 4217 currency code of the locale. Returns `null` if the currency cannot be determined.                                              |
| **`currencySymbol`**    | \`string            | null\`                                          | The currency symbol of the locale. Returns `null` if the currency symbol cannot be determined.                                              |
| **`decimalSeparator`**  | \`string            | null\`                                          | The character used to separate the integer part from the fractional part of a number. Returns `null` if the separator cannot be determined. |
| **`groupingSeparator`** | \`string            | null\`                                          | The character used to group digits of the integer part of a number. Returns `null` if the separator cannot be determined.                   |
| **`languageCode`**      | `string`            | The ISO 639 language code of the locale.        | 0.1.0                                                                                                                                       |
| **`languageTag`**       | `string`            | The BCP 47 language tag of the locale.          | 0.1.0                                                                                                                                       |
| **`measurementSystem`** | \`MeasurementSystem | null\`                                          | The measurement system used by the locale. Returns `null` if the measurement system cannot be determined.                                   |
| **`regionCode`**        | \`string            | null\`                                          | The ISO 3166 region code of the locale. Returns `null` if the region cannot be determined.                                                  |
| **`textDirection`**     | `TextDirection`     | The writing direction of the locale's language. | 0.1.0                                                                                                                                       |

#### GetSettingsResult

| Prop                  | Type      | Description                                                                                                                           | Since |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`firstDayOfWeek`**  | `number`  | The first day of the week as configured by the user. The value follows the ISO 8601 convention where `1` is Monday and `7` is Sunday. | 0.1.0 |
| **`timeZone`**        | `string`  | The identifier of the user's current time zone.                                                                                       | 0.1.0 |
| **`uses24HourClock`** | `boolean` | Whether the user prefers a 24-hour clock over a 12-hour clock.                                                                        | 0.1.0 |

### Type Aliases

#### MeasurementSystem

The measurement system used by a locale.

- `metric`: The metric system (e.g. meters, kilograms).
- `us`: The United States customary system (e.g. feet, pounds).
- `uk`: The United Kingdom imperial system.

`'metric' | 'us' | 'uk'`

#### TextDirection

The writing direction of a language.

- `ltr`: Left-to-right (e.g. English, German).
- `rtl`: Right-to-left (e.g. Arabic, Hebrew).

`'ltr' | 'rtl'`

## Platform Support

The plugin returns `null` for any field that a platform cannot determine. On the **Web** platform, `currencyCode`, `currencySymbol`, and `measurementSystem` are always `null`, because the browser does not expose this information.

## FAQ

### How is this plugin different from other similar plugins?

It reads the user's complete localization picture in one fully typed API — ordered preferred locales, currency and number separators, text direction, measurement system, time zone, clock format, and first day of the week — across Android, iOS, and the Web. It's honest about platform limits, returning `null` for fields a platform can't determine. If you only need the current language, a minimal lookup is enough; if you want to format numbers, currencies, dates, and layouts to match each user's region, this plugin is designed for exactly that.

### Why are some locale fields `null` on the Web?

The plugin returns `null` for any field that a platform cannot determine. On the Web, `currencyCode`, `currencySymbol`, and `measurementSystem` are always `null` because the browser does not expose this information. On Android and iOS, the plugin has full access to the system's localization settings.

### Do I need any permissions to use this plugin?

No, reading the user's localization preferences does not require any permissions. No additional configuration is required on any platform either, so the plugin works right after [installation](#installation).

### How do I detect right-to-left languages?

Every locale returned by `getLocales()` contains a `textDirection` property that is either `ltr` (left-to-right, e.g. English or German) or `rtl` (right-to-left, e.g. Arabic or Hebrew). You can use this value to switch the layout direction of your app.

### How is this plugin different from the App Language plugin?

The Localization plugin reads the user's system-level preferences, such as preferred locales, time zone, and regional formatting settings. The [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/) plugin, on the other hand, manages the app's own language override, independent of the device language.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/): Manage the app's own language override, independent of the device language.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Native date and time selection with localization and theming support.
- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, and operating system.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/localization/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/localization/LICENSE).

# Capacitor Mail Composer Plugin

Capacitor plugin to open the native email composer.

## Features

- ✉️ **Compose**: Open the native email composer prefilled with recipients, subject and body.
- 📎 **Attachments**: Attach one or more files from the file system or from base64 strings.
- ✅ **Availability**: Check whether the device is able to compose and send emails.
- 🌐 **Cross-platform**: Supports Android, iOS and the web (via `mailto:`).
- 🤝 **Compatibility**: Works alongside the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/), [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Mail Composer plugin is typically used whenever an app wants the user to send an email, for example:

- **Support and feedback**: Open a prefilled email to your support address with a subject and body so users can reach out with one tap.
- **Bug reports**: Attach log files or screenshots to a bug report email using the `attachments` option, either from the file system or directly from a base64 string.
- **Sharing content**: Let users share content from your app via email with prefilled recipients, subject, and body.
- **Invitations**: Prefill invitation emails with CC and BCC recipients that the user only needs to review and send.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-mail-composer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-mail-composer
npx cap sync
```

### Android

#### Attachments

To attach files, the plugin uses the [`FileProvider`](https://developer.android.com/reference/androidx/core/content/FileProvider) that Capacitor already registers for your app (authority `${applicationId}.fileprovider`). Make sure that the directories your attachments are stored in are covered by the `res/xml/file_paths.xml` resource of your app. Otherwise, the `composeMail(...)` method will reject with an error.

Attachments that are provided as base64 strings are written to the cache directory of your app, which the default `res/xml/file_paths.xml` resource of a Capacitor app already covers with a `cache-path` entry.

### Web

On the web, the plugin builds a `mailto:` URL and opens it. This has the following limitations:

- Attachments are **not** supported and cause the `composeMail(...)` method to reject.
- HTML bodies are **not** supported. The body is always sent as plain text.
- The overall URL length is limited, so long bodies may be truncated.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the device can send emails and how to open the native email composer.

### Check whether the device can send emails

Before opening the composer, check whether the device is able to compose and send emails. On iOS, this returns `true` only if a mail account is configured. On Android, it returns `true` if a mail app is installed. On the web, it always returns `true`:

```
import { MailComposer } from '@capawesome/capacitor-mail-composer';

const canComposeMail = async () => {
  const { canCompose } = await MailComposer.canComposeMail();
  return canCompose;
};
```

### Compose an email

Open the native email composer prefilled with recipients, subject, and body. The user reviews the email and decides whether to send it. Note that on Android, the returned `status` is always `unknown`:

```
import { MailComposer } from '@capawesome/capacitor-mail-composer';

const composeMail = async () => {
  const { status } = await MailComposer.composeMail({
    to: ['jane@example.com'],
    cc: ['john@example.com'],
    subject: 'Hello World',
    body: 'This is the body of the email.',
  });
  return status;
};
```

### Compose an email with attachments

Attach a file from the file system using the `path` property, or attach a file that only exists in memory using the `data` and `name` properties. Attachments are not supported on the web:

```
import { MailComposer } from '@capawesome/capacitor-mail-composer';

const composeMailWithAttachments = async () => {
  await MailComposer.composeMail({
    to: ['support@example.com'],
    subject: 'Bug report',
    attachments: [
      { path: '/path/to/screenshot.png' },
      { data: 'SGVsbG8gV29ybGQ=', name: 'log.txt' },
    ],
  });
};
```

## API

- [`canComposeMail()`](#cancomposemail)
- [`composeMail(...)`](#composemail)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### canComposeMail()

```
canComposeMail() => Promise<CanComposeMailResult>
```

Check whether the device is able to compose and send emails.

On iOS, this returns `true` only if a mail account is configured. On Android, this returns `true` if a mail app is installed. On the web, this always returns `true` (best effort, not verifiable).

**Returns:** `Promise<CanComposeMailResult>`

**Since:** 0.1.0

______________________________________________________________________

### composeMail(...)

```
composeMail(options: ComposeMailOptions) => Promise<ComposeMailResult>
```

Open the native email composer prefilled with the provided data.

The user reviews the email and decides whether to send it. The plugin never sends the email itself.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `ComposeMailOptions` |

**Returns:** `Promise<ComposeMailResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CanComposeMailResult

| Prop             | Type      | Description                                            | Since |
| ---------------- | --------- | ------------------------------------------------------ | ----- |
| **`canCompose`** | `boolean` | Whether the device is able to compose and send emails. | 0.1.0 |

#### ComposeMailResult

| Prop         | Type                | Description                                                                                                                                                | Since |
| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`status`** | `MailComposeStatus` | The status of the email compose operation. **Note**: On Android, the status is always `unknown` because the mail intent does not return a reliable result. | 0.1.0 |

#### ComposeMailOptions

| Prop              | Type               | Description                                                                                                                                                                                         | Default | Since |
| ----------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`attachments`** | `MailAttachment[]` | The files to attach to the email. Attachments are not supported on the web.                                                                                                                         |         | 0.1.0 |
| **`bcc`**         | `string[]`         | The email addresses of the blind carbon copy (BCC) recipients.                                                                                                                                      |         | 0.1.0 |
| **`body`**        | `string`           | The body of the email.                                                                                                                                                                              |         | 0.1.0 |
| **`cc`**          | `string[]`         | The email addresses of the carbon copy (CC) recipients.                                                                                                                                             |         | 0.1.0 |
| **`isHtml`**      | `boolean`          | Whether the body should be interpreted as HTML. **Note**: On Android, HTML is best-effort as many mail apps ignore it. On the web, HTML is not supported and the body is always sent as plain text. | `false` | 0.1.0 |
| **`subject`**     | `string`           | The subject of the email.                                                                                                                                                                           |         | 0.1.0 |
| **`to`**          | `string[]`         | The email addresses of the primary recipients.                                                                                                                                                      |         | 0.1.0 |

#### MailAttachment

| Prop       | Type     | Description                                                                                                                                                                                                                                                                                                  | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`data`** | `string` | The content of the file to attach, encoded as a base64 string. Either `data` or `path` must be provided. If both are provided, `path` is used. **Attention**: The entire file is loaded into memory as a base64 string, which can lead to app crashes for large files. Use `path` instead whenever possible. | 0.2.0 |
| **`name`** | `string` | The file name of the attachment, including the file extension. Must be provided if `data` is provided. Ignored if `path` is provided, because the file name is then derived from the path.                                                                                                                   | 0.2.0 |
| **`path`** | `string` | The absolute file path or `file://` URI of the file to attach. Either `data` or `path` must be provided.                                                                                                                                                                                                     | 0.2.0 |

### Type Aliases

#### MailComposeStatus

The status of an email compose operation.

- `sent`: The email was sent.
- `saved`: The email was saved as a draft.
- `canceled`: The user canceled the operation.
- `unknown`: The status is unknown.

`'sent' | 'saved' | 'canceled' | 'unknown'`

## Platform Support

Keep the following platform-specific behavior in mind:

- **Status**: On Android, the `status` returned by `composeMail(...)` is always `unknown` because the mail intent does not return a reliable result. On iOS, the real status is returned via the delegate. On the web, the status is always `unknown`.
- **HTML body**: On Android, the `isHtml` option is best-effort because many mail apps ignore HTML content. On the web, HTML is not supported at all.
- **No mail account**: On iOS, `composeMail(...)` rejects as unavailable if no mail account is configured. Use `canComposeMail(...)` to check upfront.

## FAQ

### How is this plugin different from other similar plugins?

It opens the native email composer prefilled with recipients, subject, body, and CC and BCC, and supports file attachments and HTML bodies through a fully typed API on Android, iOS, and the Web. A `canComposeMail()` check lets you confirm the device can actually send mail before you show the feature, and the user always stays in control of sending. If you only need a plain `mailto:` link, a simpler approach is fine; if you need attachments, rich bodies, and reliable capability detection, this plugin is built for exactly that.

### Does the plugin send the email itself?

No, the plugin only opens the native email composer prefilled with the provided data. The user reviews the email and decides whether to send it. The email is always sent through the user's own mail app and account.

### Why is the status always `unknown` on Android?

On Android, the mail intent does not return a reliable result, so the `status` returned by `composeMail` is always `unknown`. On iOS, the real status (`sent`, `saved`, or `canceled`) is returned. On the web, the status is always `unknown` as well.

### Why does `composeMail` reject on iOS?

On iOS, `composeMail` rejects as unavailable if no mail account is configured on the device. Use `canComposeMail` upfront to check whether the device is able to compose and send emails, and only show your email feature if it returns `true`.

### Why does attaching a file fail on Android?

On Android, the plugin shares attachments through the [`FileProvider`](https://developer.android.com/reference/androidx/core/content/FileProvider) that Capacitor already registers for your app. If the directory a file is stored in is not covered by the `res/xml/file_paths.xml` resource of your app, `composeMail` rejects with an error. See the [Installation](#installation) section for details.

### How do I attach a file that is not stored on the file system?

Provide the content of the file as a base64 string using the `data` property of an attachment and set the `name` property to the file name including the file extension. This is useful for files that only exist in memory, for example a log file that you keep in IndexedDB. The plugin takes care of handing the content over to the mail app, so you do not need to write the file to the file system yourself.

### Why does my app crash when attaching large files?

Attachments provided via the `data` property are loaded into memory as a base64 string, which can lead to out of memory (OOM) crashes for large files. Whenever the file is available on the file system, use the `path` property instead.

### Are attachments supported on the web?

No, on the web the plugin builds a `mailto:` URL, which cannot carry attachments, so `composeMail` rejects if attachments are provided. Also keep in mind that HTML bodies are not supported on the web and long bodies may be truncated due to the URL length limit.

### Can I send HTML emails?

Yes, set the `isHtml` option to `true` to have the body interpreted as HTML. On iOS, this is fully supported. On Android, it is best-effort because many mail apps ignore HTML content. On the web, HTML is not supported and the body is always sent as plain text.

## Related Plugins

- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select files to attach to an email.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.
- [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/mail-composer/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/mail-composer/LICENSE).

# Capacitor Managed Configurations Plugin

Capacitor plugin to access managed configuration settings.

## Use Cases

The Managed Configurations plugin is typically used in enterprise apps that are distributed through an EMM or MDM solution, for example:

- **Preconfigured server settings**: Read a server URL or port that the organization's IT department has configured, instead of asking the user to enter it.
- **Policy-driven features**: Use boolean configuration entries to enable or disable features per deployment, such as allowing downloads on cellular connections.
- **Multi-tenant deployments**: Ship a single app to multiple organizations and adapt it at runtime based on the managed configuration values of each tenant.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-managed-configurations` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-managed-configurations
npx cap sync
```

### Android

See [Define managed configurations](https://developer.android.com/work/managed-configurations#define-configuration) and follow the instructions to declare the app's managed configurations correctly.

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to read managed configuration values as strings, numbers, and booleans.

### Read managed configuration values

Fetch the value associated with a given key as a string, number, or boolean. The result contains `null` if no mapping exists for the given key. These methods are only available on Android and iOS:

```
import { ManagedConfigurations } from '@capawesome/capacitor-managed-configurations';

const getString = async () => {
  const result = await ManagedConfigurations.getString({ key: 'server_url' });
  return result.value;
};

const getNumber = async () => {
  const result = await ManagedConfigurations.getNumber({ key: 'server_port' });
  return result.value;
};

const getBoolean = async () => {
  const result = await ManagedConfigurations.getBoolean({
    key: 'download_on_cellular',
  });
  return result.value;
};
```

## API

- [`getString(...)`](#getstring)
- [`getNumber(...)`](#getnumber)
- [`getBoolean(...)`](#getboolean)
- [Interfaces](#interfaces)

### getString(...)

```
getString(options: GetOptions) => Promise<GetResult<string>>
```

Fetches the value associated with the given key, or `null` if no mapping exists for the given key.

Only available on Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetResult<string>>`

______________________________________________________________________

### getNumber(...)

```
getNumber(options: GetOptions) => Promise<GetResult<number>>
```

Fetches the value associated with the given key, or `null` if no mapping exists for the given key.

Only available on Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetResult<number>>`

______________________________________________________________________

### getBoolean(...)

```
getBoolean(options: GetOptions) => Promise<GetResult<boolean>>
```

Fetches the value associated with the given key, or `null` if no mapping exists for the given key.

Only available on Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetResult<boolean>>`

______________________________________________________________________

### Interfaces

#### GetResult

| Prop        | Type | Description |
| ----------- | ---- | ----------- |
| **`value`** | \`T  | null\`      |

#### GetOptions

| Prop      | Type     | Description                             |
| --------- | -------- | --------------------------------------- |
| **`key`** | `string` | Unique key for the configuration entry. |

## Test your implementation

On **Android**, see [Set up device owner for testing](https://source.android.com/devices/tech/admin/testing-setup#set_up_the_device_owner_for_testing) and follow the instructions to set up a device owner testing environment.

On **iOS**, you need to install the app as a [managed app](https://support.apple.com/guide/deployment/distribute-managed-apps-dep575bfed86/web) with a MDM solution.

## FAQ

### What are managed configurations?

Managed configurations are settings that an organization's EMM or MDM solution pushes to an app, for example a server URL or a feature toggle. This plugin lets your Capacitor app read these settings at runtime using the `getString`, `getNumber`, and `getBoolean` methods.

### Should I use this plugin or the Intune plugin?

Organizations can deliver app configuration through two different channels, and administrators frequently mix them up. This plugin covers the **MDM channel**; the [Intune](https://capawesome.io/docs/sdks/capacitor/intune/) plugin covers the **MAM channel**:

|                            | MDM channel (this plugin)                                 | MAM channel ([Intune](https://capawesome.io/docs/sdks/capacitor/intune/)) |
| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
| Device enrollment required | Yes                                                       | No                                                                        |
| Delivered via              | `RestrictionsManager` / `com.apple.configuration.managed` | Intune App SDK (Intune service)                                           |
| Targeted at                | The device                                                | The signed-in account (identity)                                          |
| EMM vendor                 | Any EMM/MDM vendor                                        | Microsoft Intune only                                                     |
| Typical scenario           | Corporate-owned, fully managed devices                    | BYOD / app protection without device management                           |

If your organization deploys the app configuration policy with **"Managed devices"** as the delivery channel in the Intune admin center, use this plugin. If it is deployed with **"Managed apps"**, use the Intune plugin. Apps that must support both scenarios should read both channels.

### What happens if a configuration key does not exist?

The `getString`, `getNumber`, and `getBoolean` methods return a result whose `value` is `null` if no mapping exists for the given key. Your app should handle this case, for example by falling back to a default value.

### Do I need to declare the managed configurations in my app?

On Android, yes. You need to declare your app's managed configurations as described in [Define managed configurations](https://developer.android.com/work/managed-configurations#define-configuration) so that EMM solutions can discover and set them. See the [Installation](#installation) section for details.

### How can I test managed configurations during development?

On Android, you can set up a device owner testing environment as described in [Set up device owner for testing](https://source.android.com/devices/tech/admin/testing-setup#set_up_the_device_owner_for_testing). On iOS, the app must be installed as a managed app through an MDM solution. See the [Test your implementation](#test-your-implementation) section for details.

### Is the Web platform supported?

No, the `getString`, `getNumber`, and `getBoolean` methods are only available on Android and iOS. Managed configurations are a concept of mobile device management, which does not exist in the browser.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API and App Attest.
- [Intune](https://capawesome.io/docs/sdks/capacitor/intune/): Protect corporate data with Microsoft Intune Mobile Application Management (the MAM channel counterpart to this plugin).
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/managed-configurations/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/managed-configurations/LICENSE).

## Credits

This plugin is based on the [Capacitor Managed Configurations](https://github.com/capawesome-team/capacitor-managed-configurations) plugin. Thanks to everyone who contributed to the project!

# Capacitor MapLibre Plugin

Unofficial Capacitor plugin to create native [MapLibre](https://maplibre.org/) maps on Android, iOS, and Web.[1](#fn:1)

## Features

The Capacitor MapLibre plugin renders interactive maps with the native MapLibre SDKs on Android and iOS, and with MapLibre GL JS on the Web. Here are some of the key features:

- 🗺️ **Native Rendering**: Renders a native map view on Android and iOS instead of a map inside the web view.
- 🆓 **No API Key**: Built on the open-source MapLibre stack, so no vendor account or API key is required.
- 🎨 **Map Styles**: Load any MapLibre style from a URL or a JSON string, and swap it at runtime.
- 🎥 **Camera Controls**: Set center, zoom, bearing and pitch, or fit bounds — animated or instantly.
- 📍 **Markers**: Add markers with custom icons, anchors, sizes, opacity and rotation, and update them with smooth animations.
- ✋ **Draggable Markers**: Let users drag markers and react to drag events on Android and Web.
- 〰️ **Polylines**: Draw and update routes and tracks with custom color, width and opacity.
- 🧬 **GeoJSON**: Add GeoJSON sources from data or URL and render them with styled line, fill and circle layers.
- 🧭 **User Location**: Display the location of the user and follow it with course or heading tracking modes.
- 🎛️ **Gesture Controls**: Enable or disable panning, zooming, rotating and tilting at any time.
- 🧩 **Multi-Instance**: Create and control multiple maps at the same time by ID.
- 🪟 **DOM Overlays**: Place HTML elements such as floating action buttons or bottom sheets above the map — they just work.
- 🔄 **Automatic Sync**: The native map follows the position and scroll offset of its element automatically.
- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The MapLibre plugin is typically used wherever you want to show geographical data in your app, for example:

- **Delivery & fleet tracking**: Follow vehicles live with animated markers and rotation.
- **Store & branch locators**: Display locations as markers and zoom to the results of a search.
- **Outdoor & fitness apps**: Render recorded tracks as polylines and follow the location of the user.
- **Field service**: Show jobs, areas and routes from GeoJSON data on a native map.
- **Real estate & travel**: Browse listings on a map with custom styles that match your brand.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [A Google Maps Alternative for Capacitor Apps](https://capawesome.io/blog/alternative-to-the-capacitor-google-maps-plugin/): Compares `@capacitor/google-maps` with this plugin — no billing account, no API key, and Web support.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-maplibre` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-maplibre maplibre-gl
npx cap sync
```

### Android

On Android, the plugin uses the [MapLibre Native SDK for Android](https://github.com/maplibre/maplibre-native).

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$mapLibreVersion` version of `org.maplibre.gl:android-sdk-vulkan-opengl` (default: `13.5.0`)
- `$mapLibreAnnotationVersion` version of `org.maplibre.gl:android-plugin-annotation` (default: `4.0.0`)

#### Permissions

Location permissions are only required if you want to display the location of the user on the map. In that case, add the following elements to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if you want to display the location of the user on the map. -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
```

### iOS

On iOS, the plugin uses the [MapLibre Native SDK for iOS](https://github.com/maplibre/maplibre-native). It can be integrated via Swift Package Manager or CocoaPods.

If you want to display the location of the user on the map, add the `NSLocationWhenInUseUsageDescription` key to your `Info.plist` file:

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>The app needs your location to display it on the map.</string>
```

Without this key, `checkPermissions()`, `requestPermissions()` and `enableUserLocation(...)` reject with an error.

### Web

The web implementation uses [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/), which is not bundled with the plugin. Its stylesheet is not bundled either, so you must import it once in your app:

```
import 'maplibre-gl/dist/maplibre-gl.css';
```

Without the stylesheet, the map canvas and the markers are mispositioned.

The `maplibre-gl` package is only required on the Web platform. On Android and iOS, the map is rendered by the native MapLibre SDKs.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Getting started

Add an **empty** element to your app that defines the position and size of the map:

```
<div id="map"></div>
```

```
#map {
  /* The map must not have a background so that the native map stays visible. */
  background: transparent;
  height: 400px;
  width: 100%;
}
```

On Android and iOS, the map is rendered as a native view **behind** the web view. Your app must therefore fulfill the following contract:

- The map element must be **empty**. Do not render any content into it.
- The map element **and every ancestor** that covers the map region (including `body`) must have a transparent background (`background: transparent`). Otherwise the web view paints over the native map and the map is not visible.

Elements that are not ancestors of the map element, such as floating action buttons or bottom sheets, can be layered above the map as usual. The plugin keeps the position and size of the native map in sync with the map element automatically, including while the page is scrolled or resized.

### Create a map

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

const createMap = async () => {
  await MapLibre.createMap({
    center: { latitude: 48.137154, longitude: 11.576124 },
    elementId: 'map',
    mapId: 'my-map',
    styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
    zoom: 12,
  });
};
```

If no style is provided, the [MapLibre demo style](https://demotiles.maplibre.org/style.json) is used, which is a test style and not intended for production use (see [FAQ](#where-do-i-get-map-styles-and-do-i-need-an-api-key)).

### Move the camera

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

const moveCamera = async () => {
  await MapLibre.setCamera({
    animate: true,
    animationDuration: 1000,
    bearing: 30,
    center: { latitude: 52.520008, longitude: 13.404954 },
    mapId: 'my-map',
    pitch: 45,
    zoom: 11,
  });
  await MapLibre.fitBounds({
    animate: true,
    bounds: {
      northeast: { latitude: 55.058347, longitude: 15.041896 },
      southwest: { latitude: 47.270111, longitude: 5.866342 },
    },
    mapId: 'my-map',
    padding: { bottom: 32, left: 32, right: 32, top: 32 },
  });
};
```

### Add markers

```
import { MapLibre, MarkerIconAnchor } from '@capawesome/capacitor-maplibre';

const addMarker = async () => {
  await MapLibre.addMarker({
    mapId: 'my-map',
    marker: {
      coordinates: { latitude: 48.137154, longitude: 11.576124 },
      iconAnchor: MarkerIconAnchor.Center,
      iconSize: { height: 32, width: 32 },
      iconUrl: 'https://example.com/marker.png',
      id: 'my-marker',
    },
  });
};

const moveMarker = async () => {
  await MapLibre.updateMarkerById({
    animate: true,
    animationDuration: 1000,
    coordinates: { latitude: 48.370545, longitude: 10.89779 },
    mapId: 'my-map',
    markerId: 'my-marker',
    rotation: 90,
  });
};

const removeMarker = async () => {
  await MapLibre.removeMarkerById({ mapId: 'my-map', markerId: 'my-marker' });
};
```

### Add polylines

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

const addPolyline = async () => {
  await MapLibre.addPolyline({
    mapId: 'my-map',
    polyline: {
      color: '#3887be',
      coordinates: [
        { latitude: 48.137154, longitude: 11.576124 },
        { latitude: 49.45203, longitude: 11.076665 },
        { latitude: 52.520008, longitude: 13.404954 },
      ],
      id: 'my-polyline',
      width: 5,
    },
  });
};
```

### Add GeoJSON data

```
import { LayerType, MapLibre } from '@capawesome/capacitor-maplibre';

const addGeoJson = async () => {
  await MapLibre.addGeoJsonSource({
    mapId: 'my-map',
    sourceId: 'my-source',
    url: 'https://example.com/routes.geojson',
  });
  await MapLibre.addLayer({
    layerId: 'my-layer',
    mapId: 'my-map',
    paint: { lineColor: '#3887be', lineWidth: 4 },
    sourceId: 'my-source',
    type: LayerType.Line,
  });
};
```

### Display the location of the user

```
import { MapLibre, UserTrackingMode } from '@capawesome/capacitor-maplibre';

const enableUserLocation = async () => {
  let status = await MapLibre.checkPermissions();
  if (status.location === 'prompt') {
    status = await MapLibre.requestPermissions();
  }
  if (status.location !== 'granted') {
    return;
  }
  await MapLibre.enableUserLocation({
    mapId: 'my-map',
    trackingMode: UserTrackingMode.Follow,
  });
};
```

### Listen for events

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

const addListeners = async () => {
  await MapLibre.addListener('mapClick', event => {
    console.log('Map clicked:', event.coordinates);
  });
  await MapLibre.addListener('markerClick', event => {
    console.log('Marker clicked:', event.markerId);
  });
  await MapLibre.addListener('cameraIdle', event => {
    console.log('Camera idle:', event.camera);
  });
};
```

### Destroy a map

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

const destroyMap = async () => {
  await MapLibre.destroyMap({ mapId: 'my-map' });
};
```

## API

- [`addGeoJsonSource(...)`](#addgeojsonsource)
- [`addLayer(...)`](#addlayer)
- [`addMarker(...)`](#addmarker)
- [`addMarkers(...)`](#addmarkers)
- [`addPolyline(...)`](#addpolyline)
- [`addPolylines(...)`](#addpolylines)
- [`checkPermissions()`](#checkpermissions)
- [`createMap(...)`](#createmap)
- [`destroyMap(...)`](#destroymap)
- [`disableUserLocation(...)`](#disableuserlocation)
- [`elementFromPointResult(...)`](#elementfrompointresult)
- [`enableUserLocation(...)`](#enableuserlocation)
- [`fitBounds(...)`](#fitbounds)
- [`getCamera(...)`](#getcamera)
- [`removeAllMarkers(...)`](#removeallmarkers)
- [`removeAllPolylines(...)`](#removeallpolylines)
- [`removeGeoJsonSourceById(...)`](#removegeojsonsourcebyid)
- [`removeLayerById(...)`](#removelayerbyid)
- [`removeMarkerById(...)`](#removemarkerbyid)
- [`removeMarkersByIds(...)`](#removemarkersbyids)
- [`removePolylineById(...)`](#removepolylinebyid)
- [`removePolylinesByIds(...)`](#removepolylinesbyids)
- [`requestPermissions()`](#requestpermissions)
- [`setCamera(...)`](#setcamera)
- [`setFrame(...)`](#setframe)
- [`setGesturesEnabled(...)`](#setgesturesenabled)
- [`setStyle(...)`](#setstyle)
- [`updateGeoJsonSourceById(...)`](#updategeojsonsourcebyid)
- [`updateMarkerById(...)`](#updatemarkerbyid)
- [`updatePolylineById(...)`](#updatepolylinebyid)
- [`addListener('cameraIdle', ...)`](#addlistenercameraidle-)
- [`addListener('cameraMoveStarted', ...)`](#addlistenercameramovestarted-)
- [`addListener('elementFromPointRequest', ...)`](#addlistenerelementfrompointrequest-)
- [`addListener('mapClick', ...)`](#addlistenermapclick-)
- [`addListener('markerClick', ...)`](#addlistenermarkerclick-)
- [`addListener('markerDrag', ...)`](#addlistenermarkerdrag-)
- [`addListener('markerDragEnd', ...)`](#addlistenermarkerdragend-)
- [`addListener('markerDragStart', ...)`](#addlistenermarkerdragstart-)
- [`addListener('userLocationChange', ...)`](#addlisteneruserlocationchange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### addGeoJsonSource(...)

```
addGeoJsonSource(options: AddGeoJsonSourceOptions) => Promise<void>
```

Add a GeoJSON source to the map.

Use `addLayer(...)` to render the data of the source.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `AddGeoJsonSourceOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addLayer(...)

```
addLayer(options: AddLayerOptions) => Promise<void>
```

Add a layer to the map that renders the data of a GeoJSON source.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `AddLayerOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addMarker(...)

```
addMarker(options: AddMarkerOptions) => Promise<void>
```

Add a marker to the map.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AddMarkerOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addMarkers(...)

```
addMarkers(options: AddMarkersOptions) => Promise<void>
```

Add multiple markers to the map.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `AddMarkersOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addPolyline(...)

```
addPolyline(options: AddPolylineOptions) => Promise<void>
```

Add a polyline to the map.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `AddPolylineOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addPolylines(...)

```
addPolylines(options: AddPolylinesOptions) => Promise<void>
```

Add multiple polylines to the map.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `AddPolylinesOptions` |

**Since:** 0.1.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the location permission.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### createMap(...)

```
createMap(options: CreateMapOptions) => Promise<void>
```

Create a new map.

The map is rendered into the element with the given element ID. On Android and iOS, the map is rendered as a native view behind the web view, so the element and everything above the map must be transparent.

The promise resolves as soon as the style of the map has finished loading.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `CreateMapOptions` |

**Since:** 0.1.0

______________________________________________________________________

### destroyMap(...)

```
destroyMap(options: DestroyMapOptions) => Promise<void>
```

Destroy a map and release all its resources.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DestroyMapOptions` |

**Since:** 0.1.0

______________________________________________________________________

### disableUserLocation(...)

```
disableUserLocation(options: DisableUserLocationOptions) => Promise<void>
```

Stop displaying the location of the user on the map.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `DisableUserLocationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### elementFromPointResult(...)

```
elementFromPointResult(options: ElementFromPointResultOptions) => Promise<void>
```

Answer an `elementFromPointRequest` event.

This method is called automatically by the plugin and must not be called manually.

Only available on Android.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `ElementFromPointResultOptions` |

**Since:** 0.1.0

______________________________________________________________________

### enableUserLocation(...)

```
enableUserLocation(options: EnableUserLocationOptions) => Promise<void>
```

Display the location of the user on the map.

Call this method again to change the tracking mode.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `EnableUserLocationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### fitBounds(...)

```
fitBounds(options: FitBoundsOptions) => Promise<void>
```

Move the camera so that the given bounds are visible.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `FitBoundsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getCamera(...)

```
getCamera(options: GetCameraOptions) => Promise<GetCameraResult>
```

Get the current camera of the map.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GetCameraOptions` |

**Returns:** `Promise<GetCameraResult>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllMarkers(...)

```
removeAllMarkers(options: RemoveAllMarkersOptions) => Promise<void>
```

Remove all markers from the map.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `RemoveAllMarkersOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeAllPolylines(...)

```
removeAllPolylines(options: RemoveAllPolylinesOptions) => Promise<void>
```

Remove all polylines from the map.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RemoveAllPolylinesOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeGeoJsonSourceById(...)

```
removeGeoJsonSourceById(options: RemoveGeoJsonSourceByIdOptions) => Promise<void>
```

Remove a GeoJSON source from the map.

All layers that use the source must be removed first.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `RemoveGeoJsonSourceByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeLayerById(...)

```
removeLayerById(options: RemoveLayerByIdOptions) => Promise<void>
```

Remove a layer from the map.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `RemoveLayerByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeMarkerById(...)

```
removeMarkerById(options: RemoveMarkerByIdOptions) => Promise<void>
```

Remove a marker from the map.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `RemoveMarkerByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeMarkersByIds(...)

```
removeMarkersByIds(options: RemoveMarkersByIdsOptions) => Promise<void>
```

Remove multiple markers from the map.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RemoveMarkersByIdsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removePolylineById(...)

```
removePolylineById(options: RemovePolylineByIdOptions) => Promise<void>
```

Remove a polyline from the map.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RemovePolylineByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removePolylinesByIds(...)

```
removePolylinesByIds(options: RemovePolylinesByIdsOptions) => Promise<void>
```

Remove multiple polylines from the map.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `RemovePolylinesByIdsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the location permission.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### setCamera(...)

```
setCamera(options: SetCameraOptions) => Promise<void>
```

Move the camera of the map.

Only the provided properties are changed.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetCameraOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setFrame(...)

```
setFrame(options: SetFrameOptions) => Promise<void>
```

Update the position and size of the map viewport.

This method is called automatically by the plugin and usually does not need to be called manually.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetFrameOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setGesturesEnabled(...)

```
setGesturesEnabled(options: SetGesturesEnabledOptions) => Promise<void>
```

Enable or disable the gestures of the map.

Only the provided gestures are changed.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SetGesturesEnabledOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setStyle(...)

```
setStyle(options: SetStyleOptions) => Promise<void>
```

Load a new style into the map.

All markers, polylines, sources and layers must be added again after the new style has been loaded.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetStyleOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updateGeoJsonSourceById(...)

```
updateGeoJsonSourceById(options: UpdateGeoJsonSourceByIdOptions) => Promise<void>
```

Update the data of a GeoJSON source.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `UpdateGeoJsonSourceByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updateMarkerById(...)

```
updateMarkerById(options: UpdateMarkerByIdOptions) => Promise<void>
```

Update a marker on the map.

Only the provided properties are changed.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `UpdateMarkerByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updatePolylineById(...)

```
updatePolylineById(options: UpdatePolylineByIdOptions) => Promise<void>
```

Update a polyline on the map.

Only the provided properties are changed.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `UpdatePolylineByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('cameraIdle', ...)

```
addListener(eventName: 'cameraIdle', listenerFunc: (event: CameraIdleEvent) => void) => Promise<PluginListenerHandle>
```

Called when the camera of a map has stopped moving.

| Param              | Type                               |
| ------------------ | ---------------------------------- |
| **`eventName`**    | `'cameraIdle'`                     |
| **`listenerFunc`** | `(event: CameraIdleEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('cameraMoveStarted', ...)

```
addListener(eventName: 'cameraMoveStarted', listenerFunc: (event: CameraMoveStartedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the camera of a map has started moving.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'cameraMoveStarted'`                     |
| **`listenerFunc`** | `(event: CameraMoveStartedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('elementFromPointRequest', ...)

```
addListener(eventName: 'elementFromPointRequest', listenerFunc: (event: ElementFromPointRequestEvent) => void) => Promise<PluginListenerHandle>
```

Called when the plugin needs to know which map is located at a point of the screen.

This event is handled automatically by the plugin and must not be handled manually.

Only available on Android.

| Param              | Type                                            |
| ------------------ | ----------------------------------------------- |
| **`eventName`**    | `'elementFromPointRequest'`                     |
| **`listenerFunc`** | `(event: ElementFromPointRequestEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('mapClick', ...)

```
addListener(eventName: 'mapClick', listenerFunc: (event: MapClickEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user taps on a map.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'mapClick'`                     |
| **`listenerFunc`** | `(event: MapClickEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('markerClick', ...)

```
addListener(eventName: 'markerClick', listenerFunc: (event: MarkerClickEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user taps on a marker.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'markerClick'`                     |
| **`listenerFunc`** | `(event: MarkerClickEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('markerDrag', ...)

```
addListener(eventName: 'markerDrag', listenerFunc: (event: MarkerDragEvent) => void) => Promise<PluginListenerHandle>
```

Called while the user drags a marker.

Only available on Android and Web.

| Param              | Type                               |
| ------------------ | ---------------------------------- |
| **`eventName`**    | `'markerDrag'`                     |
| **`listenerFunc`** | `(event: MarkerDragEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('markerDragEnd', ...)

```
addListener(eventName: 'markerDragEnd', listenerFunc: (event: MarkerDragEndEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user has stopped dragging a marker.

Only available on Android and Web.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'markerDragEnd'`                     |
| **`listenerFunc`** | `(event: MarkerDragEndEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('markerDragStart', ...)

```
addListener(eventName: 'markerDragStart', listenerFunc: (event: MarkerDragStartEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user has started dragging a marker.

Only available on Android and Web.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'markerDragStart'`                     |
| **`listenerFunc`** | `(event: MarkerDragStartEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('userLocationChange', ...)

```
addListener(eventName: 'userLocationChange', listenerFunc: (event: UserLocationChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the location of the user changes.

The event is only emitted while the location of the user is displayed on the map.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'userLocationChange'`                     |
| **`listenerFunc`** | `(event: UserLocationChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AddGeoJsonSourceOptions

| Prop           | Type                      | Description                                                                                  | Since |
| -------------- | ------------------------- | -------------------------------------------------------------------------------------------- | ----- |
| **`data`**     | `Record<string, unknown>` | The GeoJSON data of the source. Exactly one of `data` and `url` must be provided.            | 0.1.0 |
| **`mapId`**    | `string`                  | The unique identifier of the map.                                                            | 0.1.0 |
| **`sourceId`** | `string`                  | The unique identifier of the source.                                                         | 0.1.0 |
| **`url`**      | `string`                  | The URL of the GeoJSON data of the source. Exactly one of `data` and `url` must be provided. | 0.1.0 |

#### AddLayerOptions

| Prop               | Type         | Description                                                                                                                               | Since |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`belowLayerId`** | `string`     | The unique identifier of the layer below which the new layer is inserted. If not provided, the layer is added on top of all other layers. | 0.1.0 |
| **`layerId`**      | `string`     | The unique identifier of the layer.                                                                                                       | 0.1.0 |
| **`mapId`**        | `string`     | The unique identifier of the map.                                                                                                         | 0.1.0 |
| **`maxZoom`**      | `number`     | The maximum zoom level at which the layer is visible.                                                                                     | 0.1.0 |
| **`minZoom`**      | `number`     | The minimum zoom level at which the layer is visible.                                                                                     | 0.1.0 |
| **`paint`**        | `LayerPaint` | The paint properties of the layer.                                                                                                        | 0.1.0 |
| **`sourceId`**     | `string`     | The unique identifier of the source whose data is rendered by the layer.                                                                  | 0.1.0 |
| **`type`**         | `LayerType`  | The type of the layer.                                                                                                                    | 0.1.0 |

#### LayerPaint

The paint properties of a layer.

Properties that do not apply to the type of the layer are ignored.

| Prop                    | Type     | Description                                                                                                                              | Since |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`circleColor`**       | `string` | The fill color of the circles as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. Only applies to layers of type `circle`.   | 0.1.0 |
| **`circleOpacity`**     | `number` | The opacity of the circles as a value between `0` and `1`. Only applies to layers of type `circle`.                                      | 0.1.0 |
| **`circleRadius`**      | `number` | The radius of the circles in CSS pixels. Only applies to layers of type `circle`.                                                        | 0.1.0 |
| **`circleStrokeColor`** | `string` | The stroke color of the circles as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. Only applies to layers of type `circle`. | 0.1.0 |
| **`circleStrokeWidth`** | `number` | The stroke width of the circles in CSS pixels. Only applies to layers of type `circle`.                                                  | 0.1.0 |
| **`fillColor`**         | `string` | The fill color of the areas as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. Only applies to layers of type `fill`.       | 0.1.0 |
| **`fillOpacity`**       | `number` | The opacity of the areas as a value between `0` and `1`. Only applies to layers of type `fill`.                                          | 0.1.0 |
| **`fillOutlineColor`**  | `string` | The outline color of the areas as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. Only applies to layers of type `fill`.    | 0.1.0 |
| **`lineColor`**         | `string` | The color of the lines as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. Only applies to layers of type `line`.            | 0.1.0 |
| **`lineOpacity`**       | `number` | The opacity of the lines as a value between `0` and `1`. Only applies to layers of type `line`.                                          | 0.1.0 |
| **`lineWidth`**         | `number` | The width of the lines in CSS pixels. Only applies to layers of type `line`.                                                             | 0.1.0 |

#### AddMarkerOptions

| Prop         | Type     | Description                       | Since |
| ------------ | -------- | --------------------------------- | ----- |
| **`mapId`**  | `string` | The unique identifier of the map. | 0.1.0 |
| **`marker`** | `Marker` | The marker to add.                | 0.1.0 |

#### Marker

A marker on a map.

| Prop              | Type               | Description                                                                                                          | Default                   | Since |
| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----- |
| **`coordinates`** | `LatLng`           | The geographical coordinate of the marker.                                                                           |                           | 0.1.0 |
| **`draggable`**   | `boolean`          | Whether the user can drag the marker. Only available on Android and Web.                                             | `false`                   | 0.1.0 |
| **`iconAnchor`**  | `MarkerIconAnchor` | The part of the icon that is placed on the coordinate of the marker.                                                 | `MarkerIconAnchor.Bottom` | 0.1.0 |
| **`iconSize`**    | `MarkerIconSize`   | The size the icon is scaled to. If not provided, the intrinsic size of the icon is used.                             |                           | 0.1.0 |
| **`iconUrl`**     | `string`           | The URL of the icon of the marker. Must be a `https` URL or a data URI. If not provided, a default pin icon is used. |                           | 0.1.0 |
| **`id`**          | `string`           | The unique identifier of the marker.                                                                                 |                           | 0.1.0 |
| **`opacity`**     | `number`           | The opacity of the marker as a value between `0` and `1`.                                                            | `1`                       | 0.1.0 |
| **`rotation`**    | `number`           | The rotation of the icon in degrees clockwise.                                                                       | `0`                       | 0.1.0 |

#### LatLng

A geographical coordinate.

| Prop            | Type     | Description               | Since |
| --------------- | -------- | ------------------------- | ----- |
| **`latitude`**  | `number` | The latitude in degrees.  | 0.1.0 |
| **`longitude`** | `number` | The longitude in degrees. | 0.1.0 |

#### MarkerIconSize

The size of the icon of a marker in CSS pixels.

| Prop         | Type     | Description                           | Since |
| ------------ | -------- | ------------------------------------- | ----- |
| **`height`** | `number` | The height of the icon in CSS pixels. | 0.1.0 |
| **`width`**  | `number` | The width of the icon in CSS pixels.  | 0.1.0 |

#### AddMarkersOptions

| Prop          | Type       | Description                       | Since |
| ------------- | ---------- | --------------------------------- | ----- |
| **`mapId`**   | `string`   | The unique identifier of the map. | 0.1.0 |
| **`markers`** | `Marker[]` | The markers to add.               | 0.1.0 |

#### AddPolylineOptions

| Prop           | Type       | Description                       | Since |
| -------------- | ---------- | --------------------------------- | ----- |
| **`mapId`**    | `string`   | The unique identifier of the map. | 0.1.0 |
| **`polyline`** | `Polyline` | The polyline to add.              | 0.1.0 |

#### Polyline

A polyline on a map.

| Prop              | Type       | Description                                                                               | Default     | Since |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------- | ----------- | ----- |
| **`color`**       | `string`   | The color of the polyline as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. | `'#3887be'` | 0.1.0 |
| **`coordinates`** | `LatLng[]` | The geographical coordinates of the polyline.                                             |             | 0.1.0 |
| **`id`**          | `string`   | The unique identifier of the polyline.                                                    |             | 0.1.0 |
| **`opacity`**     | `number`   | The opacity of the polyline as a value between `0` and `1`.                               | `1`         | 0.1.0 |
| **`width`**       | `number`   | The width of the polyline in CSS pixels.                                                  | `4`         | 0.1.0 |

#### AddPolylinesOptions

| Prop            | Type         | Description                       | Since |
| --------------- | ------------ | --------------------------------- | ----- |
| **`mapId`**     | `string`     | The unique identifier of the map. | 0.1.0 |
| **`polylines`** | `Polyline[]` | The polylines to add.             | 0.1.0 |

#### PermissionStatus

| Prop           | Type              | Description                                      | Since |
| -------------- | ----------------- | ------------------------------------------------ | ----- |
| **`location`** | `PermissionState` | The permission state of the location permission. | 0.1.0 |

#### CreateMapOptions

| Prop            | Type              | Description                                                                                                   | Default                                       | Since |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----- |
| **`bearing`**   | `number`          | The direction the camera points in, in degrees clockwise from north.                                          | `0`                                           | 0.1.0 |
| **`center`**    | `LatLng`          | The geographical coordinate at the center of the map. If not provided, the center of the style is used.       |                                               | 0.1.0 |
| **`elementId`** | `string`          | The ID of the DOM element the map is rendered into. The element must be empty and must not have a background. |                                               | 0.1.0 |
| **`gestures`**  | `GestureSettings` | The gestures the user can perform on the map.                                                                 |                                               | 0.1.0 |
| **`mapId`**     | `string`          | The unique identifier of the map.                                                                             |                                               | 0.1.0 |
| **`maxZoom`**   | `number`          | The maximum zoom level of the map. If not provided, the maximum zoom level of the style is used.              |                                               | 0.1.0 |
| **`minZoom`**   | `number`          | The minimum zoom level of the map. If not provided, the minimum zoom level of the style is used.              |                                               | 0.1.0 |
| **`pitch`**     | `number`          | The tilt of the camera in degrees, measured from the plane of the map.                                        | `0`                                           | 0.1.0 |
| **`styleJson`** | `string`          | The style of the map as a JSON string. At most one of `styleJson` and `styleUrl` may be provided.             |                                               | 0.1.0 |
| **`styleUrl`**  | `string`          | The URL of the style of the map. At most one of `styleJson` and `styleUrl` may be provided.                   | `'https://demotiles.maplibre.org/style.json'` | 0.1.0 |
| **`zoom`**      | `number`          | The zoom level of the map.                                                                                    | `0`                                           | 0.1.0 |

#### GestureSettings

The gestures the user can perform on a map.

| Prop         | Type      | Description                                               | Default | Since |
| ------------ | --------- | --------------------------------------------------------- | ------- | ----- |
| **`pan`**    | `boolean` | Whether the user can move the camera by dragging the map. | `true`  | 0.1.0 |
| **`rotate`** | `boolean` | Whether the user can rotate the camera.                   | `true`  | 0.1.0 |
| **`tilt`**   | `boolean` | Whether the user can tilt the camera.                     | `true`  | 0.1.0 |
| **`zoom`**   | `boolean` | Whether the user can zoom the camera.                     | `true`  | 0.1.0 |

#### DestroyMapOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`mapId`** | `string` | The unique identifier of the map. | 0.1.0 |

#### DisableUserLocationOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`mapId`** | `string` | The unique identifier of the map. | 0.1.0 |

#### ElementFromPointResultOptions

| Prop            | Type     | Description                           | Since                                                                                                                |
| --------------- | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **`mapId`**     | \`string | null\`                                | The unique identifier of the map at the requested point. Must be `null` if no map is located at the requested point. |
| **`requestId`** | `string` | The unique identifier of the request. | 0.1.0                                                                                                                |

#### EnableUserLocationOptions

| Prop               | Type               | Description                                                                                                                               | Default                 | Since |
| ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----- |
| **`mapId`**        | `string`           | The unique identifier of the map.                                                                                                         |                         | 0.1.0 |
| **`trackingMode`** | `UserTrackingMode` | The mode used to track the location of the user with the camera. On Web, `FollowWithCourse` and `FollowWithHeading` behave like `Follow`. | `UserTrackingMode.None` | 0.1.0 |

#### FitBoundsOptions

| Prop                    | Type      | Description                                                | Default | Since |
| ----------------------- | --------- | ---------------------------------------------------------- | ------- | ----- |
| **`animate`**           | `boolean` | Whether the camera movement is animated.                   | `false` | 0.1.0 |
| **`animationDuration`** | `number`  | The duration of the animation in milliseconds.             | `300`   | 0.1.0 |
| **`bounds`**            | `Bounds`  | The bounds that must be visible after the camera movement. |         | 0.1.0 |
| **`mapId`**             | `string`  | The unique identifier of the map.                          |         | 0.1.0 |
| **`maxZoom`**           | `number`  | The maximum zoom level the camera may reach.               |         | 0.1.0 |
| **`padding`**           | `Padding` | The padding between the bounds and the edges of the map.   |         | 0.1.0 |

#### Bounds

A geographical area, defined by its southwest and northeast corner.

| Prop            | Type     | Description                       | Since |
| --------------- | -------- | --------------------------------- | ----- |
| **`northeast`** | `LatLng` | The northeast corner of the area. | 0.1.0 |
| **`southwest`** | `LatLng` | The southwest corner of the area. | 0.1.0 |

#### Padding

The padding between the content of a map and its edges in CSS pixels.

| Prop         | Type     | Description                                   | Default | Since |
| ------------ | -------- | --------------------------------------------- | ------- | ----- |
| **`bottom`** | `number` | The padding at the bottom edge in CSS pixels. | `0`     | 0.1.0 |
| **`left`**   | `number` | The padding at the left edge in CSS pixels.   | `0`     | 0.1.0 |
| **`right`**  | `number` | The padding at the right edge in CSS pixels.  | `0`     | 0.1.0 |
| **`top`**    | `number` | The padding at the top edge in CSS pixels.    | `0`     | 0.1.0 |

#### GetCameraResult

| Prop         | Type     | Description                    | Since |
| ------------ | -------- | ------------------------------ | ----- |
| **`camera`** | `Camera` | The current camera of the map. | 0.1.0 |

#### Camera

The camera of a map.

| Prop          | Type     | Description                                                            | Since |
| ------------- | -------- | ---------------------------------------------------------------------- | ----- |
| **`bearing`** | `number` | The direction the camera points in, in degrees clockwise from north.   | 0.1.0 |
| **`center`**  | `LatLng` | The geographical coordinate at the center of the map.                  | 0.1.0 |
| **`pitch`**   | `number` | The tilt of the camera in degrees, measured from the plane of the map. | 0.1.0 |
| **`zoom`**    | `number` | The zoom level of the map.                                             | 0.1.0 |

#### GetCameraOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`mapId`** | `string` | The unique identifier of the map. | 0.1.0 |

#### RemoveAllMarkersOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`mapId`** | `string` | The unique identifier of the map. | 0.1.0 |

#### RemoveAllPolylinesOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`mapId`** | `string` | The unique identifier of the map. | 0.1.0 |

#### RemoveGeoJsonSourceByIdOptions

| Prop           | Type     | Description                          | Since |
| -------------- | -------- | ------------------------------------ | ----- |
| **`mapId`**    | `string` | The unique identifier of the map.    | 0.1.0 |
| **`sourceId`** | `string` | The unique identifier of the source. | 0.1.0 |

#### RemoveLayerByIdOptions

| Prop          | Type     | Description                         | Since |
| ------------- | -------- | ----------------------------------- | ----- |
| **`layerId`** | `string` | The unique identifier of the layer. | 0.1.0 |
| **`mapId`**   | `string` | The unique identifier of the map.   | 0.1.0 |

#### RemoveMarkerByIdOptions

| Prop           | Type     | Description                          | Since |
| -------------- | -------- | ------------------------------------ | ----- |
| **`mapId`**    | `string` | The unique identifier of the map.    | 0.1.0 |
| **`markerId`** | `string` | The unique identifier of the marker. | 0.1.0 |

#### RemoveMarkersByIdsOptions

| Prop            | Type       | Description                            | Since |
| --------------- | ---------- | -------------------------------------- | ----- |
| **`mapId`**     | `string`   | The unique identifier of the map.      | 0.1.0 |
| **`markerIds`** | `string[]` | The unique identifiers of the markers. | 0.1.0 |

#### RemovePolylineByIdOptions

| Prop             | Type     | Description                            | Since |
| ---------------- | -------- | -------------------------------------- | ----- |
| **`mapId`**      | `string` | The unique identifier of the map.      | 0.1.0 |
| **`polylineId`** | `string` | The unique identifier of the polyline. | 0.1.0 |

#### RemovePolylinesByIdsOptions

| Prop              | Type       | Description                              | Since |
| ----------------- | ---------- | ---------------------------------------- | ----- |
| **`mapId`**       | `string`   | The unique identifier of the map.        | 0.1.0 |
| **`polylineIds`** | `string[]` | The unique identifiers of the polylines. | 0.1.0 |

#### SetCameraOptions

| Prop                    | Type      | Description                                                            | Default | Since |
| ----------------------- | --------- | ---------------------------------------------------------------------- | ------- | ----- |
| **`animate`**           | `boolean` | Whether the camera movement is animated.                               | `false` | 0.1.0 |
| **`animationDuration`** | `number`  | The duration of the animation in milliseconds.                         | `300`   | 0.1.0 |
| **`bearing`**           | `number`  | The direction the camera points in, in degrees clockwise from north.   |         | 0.1.0 |
| **`center`**            | `LatLng`  | The geographical coordinate at the center of the map.                  |         | 0.1.0 |
| **`mapId`**             | `string`  | The unique identifier of the map.                                      |         | 0.1.0 |
| **`padding`**           | `Padding` | The padding between the content of the map and its edges.              |         | 0.1.0 |
| **`pitch`**             | `number`  | The tilt of the camera in degrees, measured from the plane of the map. |         | 0.1.0 |
| **`zoom`**              | `number`  | The zoom level of the map.                                             |         | 0.1.0 |

#### SetFrameOptions

| Prop              | Type             | Description                                            | Since |
| ----------------- | ---------------- | ------------------------------------------------------ | ----- |
| **`contentSize`** | `MapContentSize` | The size of the scrollable content of the map element. | 0.1.0 |
| **`frame`**       | `MapFrame`       | The new position and size of the map viewport.         | 0.1.0 |
| **`mapId`**       | `string`         | The unique identifier of the map.                      | 0.1.0 |

#### MapContentSize

The size of the scrollable content of a map element in CSS pixels.

| Prop         | Type     | Description                              | Since |
| ------------ | -------- | ---------------------------------------- | ----- |
| **`height`** | `number` | The height of the content in CSS pixels. | 0.1.0 |
| **`width`**  | `number` | The width of the content in CSS pixels.  | 0.1.0 |

#### MapFrame

The position and size of a map in CSS pixels, relative to the viewport.

| Prop         | Type     | Description                                | Since |
| ------------ | -------- | ------------------------------------------ | ----- |
| **`height`** | `number` | The height of the map in CSS pixels.       | 0.1.0 |
| **`width`**  | `number` | The width of the map in CSS pixels.        | 0.1.0 |
| **`x`**      | `number` | The x-coordinate of the map in CSS pixels. | 0.1.0 |
| **`y`**      | `number` | The y-coordinate of the map in CSS pixels. | 0.1.0 |

#### SetGesturesEnabledOptions

| Prop         | Type      | Description                                                                                             | Since |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------- | ----- |
| **`mapId`**  | `string`  | The unique identifier of the map.                                                                       | 0.1.0 |
| **`pan`**    | `boolean` | Whether the user can move the camera by dragging the map. If not provided, the current setting is kept. | 0.1.0 |
| **`rotate`** | `boolean` | Whether the user can rotate the camera. If not provided, the current setting is kept.                   | 0.1.0 |
| **`tilt`**   | `boolean` | Whether the user can tilt the camera. If not provided, the current setting is kept.                     | 0.1.0 |
| **`zoom`**   | `boolean` | Whether the user can zoom the camera. If not provided, the current setting is kept.                     | 0.1.0 |

#### SetStyleOptions

| Prop        | Type     | Description                                                                              | Since |
| ----------- | -------- | ---------------------------------------------------------------------------------------- | ----- |
| **`json`**  | `string` | The style of the map as a JSON string. Exactly one of `json` and `url` must be provided. | 0.1.0 |
| **`mapId`** | `string` | The unique identifier of the map.                                                        | 0.1.0 |
| **`url`**   | `string` | The URL of the style of the map. Exactly one of `json` and `url` must be provided.       | 0.1.0 |

#### UpdateGeoJsonSourceByIdOptions

| Prop           | Type                      | Description                                                                                      | Since |
| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------ | ----- |
| **`data`**     | `Record<string, unknown>` | The new GeoJSON data of the source. Exactly one of `data` and `url` must be provided.            | 0.1.0 |
| **`mapId`**    | `string`                  | The unique identifier of the map.                                                                | 0.1.0 |
| **`sourceId`** | `string`                  | The unique identifier of the source.                                                             | 0.1.0 |
| **`url`**      | `string`                  | The URL of the new GeoJSON data of the source. Exactly one of `data` and `url` must be provided. | 0.1.0 |

#### UpdateMarkerByIdOptions

| Prop                    | Type               | Description                                                                 | Default | Since |
| ----------------------- | ------------------ | --------------------------------------------------------------------------- | ------- | ----- |
| **`animate`**           | `boolean`          | Whether the changes of the coordinates and the rotation are animated.       | `false` | 0.1.0 |
| **`animationDuration`** | `number`           | The duration of the animation in milliseconds.                              | `300`   | 0.1.0 |
| **`coordinates`**       | `LatLng`           | The new geographical coordinate of the marker.                              |         | 0.1.0 |
| **`draggable`**         | `boolean`          | Whether the user can drag the marker. Only available on Android and Web.    |         | 0.1.0 |
| **`iconAnchor`**        | `MarkerIconAnchor` | The part of the icon that is placed on the coordinate of the marker.        |         | 0.1.0 |
| **`iconSize`**          | `MarkerIconSize`   | The size the icon is scaled to.                                             |         | 0.1.0 |
| **`iconUrl`**           | `string`           | The URL of the new icon of the marker. Must be a `https` URL or a data URI. |         | 0.1.0 |
| **`mapId`**             | `string`           | The unique identifier of the map.                                           |         | 0.1.0 |
| **`markerId`**          | `string`           | The unique identifier of the marker.                                        |         | 0.1.0 |
| **`opacity`**           | `number`           | The opacity of the marker as a value between `0` and `1`.                   |         | 0.1.0 |
| **`rotation`**          | `number`           | The rotation of the icon in degrees clockwise.                              |         | 0.1.0 |

#### UpdatePolylineByIdOptions

| Prop              | Type       | Description                                                                               | Since |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------- | ----- |
| **`color`**       | `string`   | The color of the polyline as a hexadecimal string in the format `#RRGGBB` or `#RRGGBBAA`. | 0.1.0 |
| **`coordinates`** | `LatLng[]` | The new geographical coordinates of the polyline.                                         | 0.1.0 |
| **`mapId`**       | `string`   | The unique identifier of the map.                                                         | 0.1.0 |
| **`opacity`**     | `number`   | The opacity of the polyline as a value between `0` and `1`.                               | 0.1.0 |
| **`polylineId`**  | `string`   | The unique identifier of the polyline.                                                    | 0.1.0 |
| **`width`**       | `number`   | The width of the polyline in CSS pixels.                                                  | 0.1.0 |

#### PluginListenerHandle

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

#### CameraIdleEvent

| Prop         | Type     | Description                               | Since |
| ------------ | -------- | ----------------------------------------- | ----- |
| **`camera`** | `Camera` | The camera of the map after the movement. | 0.1.0 |
| **`mapId`**  | `string` | The unique identifier of the map.         | 0.1.0 |

#### CameraMoveStartedEvent

| Prop         | Type               | Description                               | Since |
| ------------ | ------------------ | ----------------------------------------- | ----- |
| **`mapId`**  | `string`           | The unique identifier of the map.         | 0.1.0 |
| **`reason`** | `CameraMoveReason` | The reason why the camera started moving. | 0.1.0 |

#### ElementFromPointRequestEvent

| Prop            | Type     | Description                                                            | Since |
| --------------- | -------- | ---------------------------------------------------------------------- | ----- |
| **`requestId`** | `string` | The unique identifier of the request.                                  | 0.1.0 |
| **`x`**         | `number` | The x-coordinate of the point in CSS pixels, relative to the viewport. | 0.1.0 |
| **`y`**         | `number` | The y-coordinate of the point in CSS pixels, relative to the viewport. | 0.1.0 |

#### MapClickEvent

| Prop              | Type       | Description                                     | Since |
| ----------------- | ---------- | ----------------------------------------------- | ----- |
| **`coordinates`** | `LatLng`   | The geographical coordinate the user tapped on. | 0.1.0 |
| **`mapId`**       | `string`   | The unique identifier of the map.               | 0.1.0 |
| **`point`**       | `MapPoint` | The point the user tapped on.                   | 0.1.0 |

#### MapPoint

A point on a map in CSS pixels, relative to the map element.

| Prop    | Type     | Description                                  | Since |
| ------- | -------- | -------------------------------------------- | ----- |
| **`x`** | `number` | The x-coordinate of the point in CSS pixels. | 0.1.0 |
| **`y`** | `number` | The y-coordinate of the point in CSS pixels. | 0.1.0 |

#### MarkerClickEvent

| Prop              | Type     | Description                                | Since |
| ----------------- | -------- | ------------------------------------------ | ----- |
| **`coordinates`** | `LatLng` | The geographical coordinate of the marker. | 0.1.0 |
| **`mapId`**       | `string` | The unique identifier of the map.          | 0.1.0 |
| **`markerId`**    | `string` | The unique identifier of the marker.       | 0.1.0 |

#### MarkerDragEvent

| Prop              | Type     | Description                                        | Since |
| ----------------- | -------- | -------------------------------------------------- | ----- |
| **`coordinates`** | `LatLng` | The current geographical coordinate of the marker. | 0.1.0 |
| **`mapId`**       | `string` | The unique identifier of the map.                  | 0.1.0 |
| **`markerId`**    | `string` | The unique identifier of the marker.               | 0.1.0 |

#### MarkerDragEndEvent

| Prop              | Type     | Description                                            | Since |
| ----------------- | -------- | ------------------------------------------------------ | ----- |
| **`coordinates`** | `LatLng` | The geographical coordinate the marker was dropped at. | 0.1.0 |
| **`mapId`**       | `string` | The unique identifier of the map.                      | 0.1.0 |
| **`markerId`**    | `string` | The unique identifier of the marker.                   | 0.1.0 |

#### MarkerDragStartEvent

| Prop              | Type     | Description                                              | Since |
| ----------------- | -------- | -------------------------------------------------------- | ----- |
| **`coordinates`** | `LatLng` | The geographical coordinate the marker was dragged from. | 0.1.0 |
| **`mapId`**       | `string` | The unique identifier of the map.                        | 0.1.0 |
| **`markerId`**    | `string` | The unique identifier of the marker.                     | 0.1.0 |

#### UserLocationChangeEvent

| Prop              | Type     | Description                                                          | Since |
| ----------------- | -------- | -------------------------------------------------------------------- | ----- |
| **`accuracy`**    | `number` | The accuracy of the location in meters.                              | 0.1.0 |
| **`coordinates`** | `LatLng` | The geographical coordinate of the user.                             | 0.1.0 |
| **`heading`**     | `number` | The direction the device points in, in degrees clockwise from north. | 0.1.0 |
| **`mapId`**       | `string` | The unique identifier of the map.                                    | 0.1.0 |
| **`speed`**       | `number` | The speed of the device in meters per second.                        | 0.1.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### LayerType

| Members      | Value      | Description                                    | Since |
| ------------ | ---------- | ---------------------------------------------- | ----- |
| **`Circle`** | `'circle'` | A layer that renders points as circles.        | 0.1.0 |
| **`Fill`**   | `'fill'`   | A layer that renders polygons as filled areas. | 0.1.0 |
| **`Line`**   | `'line'`   | A layer that renders line strings as lines.    | 0.1.0 |

#### MarkerIconAnchor

| Members      | Value      | Description                  | Since |
| ------------ | ---------- | ---------------------------- | ----- |
| **`Bottom`** | `'bottom'` | The bottom edge of the icon. | 0.1.0 |
| **`Center`** | `'center'` | The center of the icon.      | 0.1.0 |
| **`Left`**   | `'left'`   | The left edge of the icon.   | 0.1.0 |
| **`Right`**  | `'right'`  | The right edge of the icon.  | 0.1.0 |
| **`Top`**    | `'top'`    | The top edge of the icon.    | 0.1.0 |

#### UserTrackingMode

| Members                 | Value                 | Description                                                                                   | Since |
| ----------------------- | --------------------- | --------------------------------------------------------------------------------------------- | ----- |
| **`Follow`**            | `'follow'`            | The camera follows the location of the user.                                                  | 0.1.0 |
| **`FollowWithCourse`**  | `'followWithCourse'`  | The camera follows the location of the user and points in the direction the user moves in.    | 0.1.0 |
| **`FollowWithHeading`** | `'followWithHeading'` | The camera follows the location of the user and points in the direction the device points in. | 0.1.0 |
| **`None`**              | `'none'`              | The camera does not follow the location of the user.                                          | 0.1.0 |

#### CameraMoveReason

| Members       | Value       | Description                                    | Since |
| ------------- | ----------- | ---------------------------------------------- | ----- |
| **`Api`**     | `'api'`     | The camera was moved by a method call.         | 0.1.0 |
| **`Gesture`** | `'gesture'` | The camera was moved by a gesture of the user. | 0.1.0 |

## FAQ

### Where do I get map styles and do I need an API key?

No API key is required by the plugin itself. MapLibre is open source (BSD-licensed) and renders any style that follows the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec/). The default [demo style](https://demotiles.maplibre.org/style.json) is a test style and should not be used in production. Free providers include [CARTO basemaps](https://github.com/CartoDB/basemap-styles), [OpenFreeMap](https://openfreemap.org/) and [Versatiles](https://versatiles.org/). Commercial providers such as [MapTiler](https://www.maptiler.com/) offer styles that require their own API key. Always follow the attribution requirements and terms of service of the provider you choose.

### Why is my map not visible?

On Android and iOS, the map is rendered behind the web view. If the map element or one of its ancestors has a background color, the web view paints over the map. Make sure the map element is empty and that it and all ancestors covering the map region use `background: transparent` (see [Getting started](#getting-started)).

### Can I display HTML content above the map?

Yes. Since the native map is rendered behind the web view, any DOM element that is not an ancestor of the map element is displayed above the map. Floating action buttons, bottom sheets, overlays and dialogs work exactly as they do everywhere else in your app.

### Why are marker drag events not available on iOS?

On iOS, markers are rendered as symbol layers, which do not support native dragging yet. The `draggable` property and the `markerDrag`, `markerDragStart` and `markerDragEnd` events are therefore only available on Android and Web.

### Does this plugin work offline?

No. Styles, fonts, sprites and tiles are loaded from the network by the map. Offline tile management is not part of this version of the plugin.

## Related Plugins

- [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device compass heading.
- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/): Convert addresses into coordinates and vice versa.
- [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/): Launch navigation apps with turn-by-turn directions.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maplibre/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maplibre/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by the MapLibre organization or any of its contributors. "MapLibre" is a trademark of the MapLibre organization. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Maps Launcher Plugin

Capacitor plugin to launch navigation apps with turn-by-turn directions.

## Features

- 🧭 **Navigate**: Launch a navigation app with turn-by-turn directions to a destination.
- 🗺️ **Curated apps**: Support for Google Maps, Apple Maps (iOS) and Waze.
- 📍 **Coordinates & addresses**: Navigate to coordinates or a plain address.
- 🚗 **Travel modes**: Choose between driving, walking, bicycling and transit (best-effort per app).
- ✅ **Availability**: Check which navigation apps are installed and can be launched.
- 🤝 **Compatibility**: Works alongside the [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/), [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/) and [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Maps Launcher plugin is typically used whenever an app wants to hand the user over to a navigation app, for example:

- **Store locators**: Add a "Get directions" button that starts turn-by-turn navigation to a store or office.
- **Delivery and field service**: Launch navigation to the next stop using its coordinates.
- **Event apps**: Navigate attendees to a venue by its plain address, without needing coordinates.
- **User choice**: Detect which navigation apps are installed with `getAvailableApps` and let users pick their favorite one.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-maps-launcher` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-maps-launcher
npx cap sync
```

### Android

The plugin declares the required [package visibility](https://developer.android.com/training/package-visibility) `<queries>` for Google Maps and Waze in its own `AndroidManifest.xml`. No additional configuration is required.

### iOS

#### Application Queries Schemes

To detect and launch Google Maps and Waze, the following URL schemes must be added to the `LSApplicationQueriesSchemes` array in the `Info.plist` file of your app. Without them, `getAvailableApps(...)` reports those apps as unavailable and `navigate(...)` rejects with the `APP_NOT_AVAILABLE` error code.

```
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>comgooglemaps</string>
  <string>waze</string>
</array>
```

Apple Maps is always available and does not require any configuration.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get the available and default navigation apps and how to navigate to coordinates or an address.

### Get the available navigation apps

Check which navigation apps are installed and can be launched. On iOS, Apple Maps is always included, while Google Maps and Waze are only included if the corresponding URL schemes are declared in your `Info.plist` file (see [Installation](#installation)). Only available on Android and iOS:

```
import { MapsLauncher } from '@capawesome/capacitor-maps-launcher';

const getAvailableApps = async () => {
  const { apps } = await MapsLauncher.getAvailableApps();
  return apps;
};
```

### Get the default navigation app

Find out which navigation app is configured as the default handler for navigation intents. Returns `null` if the default app is not part of the curated list of supported apps or if no default app is set. Only available on Android:

```
import { MapsLauncher } from '@capawesome/capacitor-maps-launcher';

const getDefaultApp = async () => {
  const { app } = await MapsLauncher.getDefaultApp();
  return app;
};
```

### Navigate to coordinates

Launch a navigation app with turn-by-turn directions to a destination defined by its latitude and longitude. You can optionally specify the app to launch and the travel mode:

```
import { MapsLauncher, NavigationApp } from '@capawesome/capacitor-maps-launcher';

const navigate = async () => {
  await MapsLauncher.navigate({
    destination: {
      latitude: 37.3349,
      longitude: -122.009,
    },
    app: NavigationApp.GoogleMaps,
    travelMode: 'driving',
  });
};
```

### Navigate to an address

Instead of coordinates, you can also pass a plain address as the destination. If no `app` is provided, the system default behavior is used (a chooser on Android, Apple Maps on iOS):

```
import { MapsLauncher } from '@capawesome/capacitor-maps-launcher';

const navigateToAddress = async () => {
  await MapsLauncher.navigate({
    destination: {
      address: 'Apple Park, Cupertino, CA',
    },
  });
};
```

## API

- [`getAvailableApps()`](#getavailableapps)
- [`getDefaultApp()`](#getdefaultapp)
- [`navigate(...)`](#navigate)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### getAvailableApps()

```
getAvailableApps() => Promise<GetAvailableAppsResult>
```

Get the navigation apps that are installed and can be launched.

On iOS, Apple Maps is always included. Google Maps and Waze are only included if the corresponding `LSApplicationQueriesSchemes` entries are added to the `Info.plist` file of your app.

Only available on Android and iOS.

**Returns:** `Promise<GetAvailableAppsResult>`

**Since:** 0.1.0

______________________________________________________________________

### getDefaultApp()

```
getDefaultApp() => Promise<GetDefaultAppResult>
```

Get the navigation app that is configured as the default handler for navigation intents.

Returns `null` if the default app is not part of the curated list of supported apps or if no default app is set (i.e. the system shows a chooser).

Only available on Android.

**Returns:** `Promise<GetDefaultAppResult>`

**Since:** 0.1.0

______________________________________________________________________

### navigate(...)

```
navigate(options: NavigateOptions) => Promise<void>
```

Launch a navigation app with turn-by-turn directions to a destination.

If no `app` is provided, the system default behavior is used (a chooser on Android, Apple Maps on iOS).

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `NavigateOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetAvailableAppsResult

| Prop       | Type              | Description                                                 | Since |
| ---------- | ----------------- | ----------------------------------------------------------- | ----- |
| **`apps`** | `NavigationApp[]` | The navigation apps that are installed and can be launched. | 0.1.0 |

#### GetDefaultAppResult

| Prop      | Type            | Description | Since                                                                                                                                                                          |
| --------- | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`app`** | \`NavigationApp | null\`      | The navigation app that is configured as the default handler. Returns `null` if the default app is not part of the curated list of supported apps or if no default app is set. |

#### NavigateOptions

| Prop              | Type            | Description                                                                                                                                                                                                                                                                               | Default     | Since |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----- |
| **`app`**         | `NavigationApp` | The navigation app to launch. If not provided, the system default behavior is used (a chooser on Android, Apple Maps on iOS).                                                                                                                                                             |             | 0.1.0 |
| **`destination`** | `Destination`   | The destination to navigate to.                                                                                                                                                                                                                                                           |             | 0.1.0 |
| **`start`**       | `Destination`   | The start location of the route. If not provided, the current location of the device is used. **Note**: The support depends on the selected app. Apple Maps supports it fully, Google Maps opens the directions preview instead of starting turn-by-turn navigation, and Waze ignores it. |             | 0.1.0 |
| **`travelMode`**  | `TravelMode`    | The travel mode to use for the directions. **Note**: The support depends on the selected app and is best-effort. Waze only supports driving and ignores this option.                                                                                                                      | `'driving'` | 0.1.0 |

#### Destination

A destination is either defined by its coordinates or by its address, but not both.

| Prop            | Type     | Description                                                                                        | Since |
| --------------- | -------- | -------------------------------------------------------------------------------------------------- | ----- |
| **`address`**   | `string` | The address of the destination. Must be provided without `latitude` and `longitude`.               | 0.1.0 |
| **`latitude`**  | `number` | The latitude of the destination. Must be provided together with `longitude` and without `address`. | 0.1.0 |
| **`longitude`** | `number` | The longitude of the destination. Must be provided together with `latitude` and without `address`. | 0.1.0 |

### Type Aliases

#### TravelMode

The travel mode to use for the directions.

- `driving`: Driving directions.
- `walking`: Walking directions.
- `bicycling`: Bicycling directions.
- `transit`: Public transit directions.

`'driving' | 'walking' | 'bicycling' | 'transit'`

### Enums

#### NavigationApp

| Members          | Value           | Description                        | Since |
| ---------------- | --------------- | ---------------------------------- | ----- |
| **`AppleMaps`**  | `'APPLE_MAPS'`  | Apple Maps. Only available on iOS. | 0.1.0 |
| **`GoogleMaps`** | `'GOOGLE_MAPS'` | Google Maps.                       | 0.1.0 |
| **`Waze`**       | `'WAZE'`        | Waze.                              | 0.1.0 |

## Platform Support

The behavior of the `navigate(...)` method depends on the selected app and platform. Keep the following in mind:

### Start location

| App         | `start` support                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------- |
| Apple Maps  | Full support.                                                                                     |
| Google Maps | Supported, but opens the directions preview instead of starting turn-by-turn navigation directly. |
| Waze        | Not supported. The option is ignored.                                                             |

If `start` is not provided, the current location of the device is used.

### Travel mode

| App         | `driving` | `walking` | `bicycling` | `transit` |
| ----------- | --------- | --------- | ----------- | --------- |
| Apple Maps  | ✅        | ✅        | ❌          | ✅        |
| Google Maps | ✅        | ✅        | ✅          | ✅        |
| Waze        | ✅        | ❌        | ❌          | ❌        |

Unsupported travel modes fall back to the default behavior of the respective app. Waze only supports driving and ignores the `travelMode` option.

## FAQ

### How is this plugin different from other similar plugins?

It launches turn-by-turn navigation in Google Maps, Apple Maps, and Waze from a single fully typed API, accepting either coordinates or a plain address and supporting driving, walking, bicycling, and transit modes. It also detects which navigation apps are installed and, on Android, which one is the default handler, so you can let users pick their favorite. Per-app behavior is documented transparently, and the plugin is actively maintained against the latest Capacitor and OS versions across Android and iOS.

### Why are Google Maps and Waze reported as unavailable on iOS?

To detect and launch Google Maps and Waze on iOS, the `comgooglemaps` and `waze` URL schemes must be added to the `LSApplicationQueriesSchemes` array in the `Info.plist` file of your app. Without them, `getAvailableApps` reports those apps as unavailable and `navigate` rejects with the `APP_NOT_AVAILABLE` error code. See the [Installation](#installation) section for details.

### What happens if I do not specify a navigation app?

If no `app` is provided, the system default behavior is used: Android shows a chooser and iOS opens Apple Maps. On Android, you can use `getDefaultApp` to find out which supported navigation app is configured as the default handler.

### Which travel modes are supported?

The plugin supports the `driving`, `walking`, `bicycling`, and `transit` travel modes, but the support depends on the selected app and is best-effort. Google Maps supports all four modes, Apple Maps does not support bicycling, and Waze only supports driving and ignores the option. Unsupported travel modes fall back to the default behavior of the respective app.

### Can I set a custom start location for the route?

Yes, use the `start` option of the `navigate` method. However, the support depends on the selected app: Apple Maps supports it fully, Google Maps opens the directions preview instead of starting turn-by-turn navigation, and Waze ignores it. If no start location is provided, the current location of the device is used.

### Does the plugin work on the web?

No, the `getAvailableApps` and `navigate` methods are only available on Android and iOS, and `getDefaultApp` is only available on Android. Launching installed navigation apps is a native capability that is not available in the browser.

## Related Plugins

- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/): Launch arbitrary Android intents.
- [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/): Check if an app can be opened and open it.
- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/): Convert addresses into coordinates and vice versa.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maps-launcher/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maps-launcher/LICENSE).

# Capacitor Media Session Plugin

Capacitor plugin to interact with media controllers, volume keys and media buttons.

**Attention**: This plugin relays media control events to your JavaScript code, so it is designed for playback that runs inside the web view, such as HTML5 `<audio>` and `<video>` elements or web-based audio and video calls. For native audio playback with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) plugin, use its built-in media session integration instead, which handles the media controls natively — even when the web view is suspended.

## Features

The Capacitor Media Session plugin is one of the most complete media playback integration solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🎮 **Media Controls**: Handle hardware media keys, lock screen controls, and notification controls.
- 🎵 **Rich Metadata**: Display song title, artist, album, and artwork on lock screen and notifications.
- 🎨 **Customizable Icon**: Configure the notification icon on Android to match your app's branding.
- ▶️ **Action Handlers**: Support for play, pause, seek, next/previous track, and more.
- 📍 **Position State**: Track and display playback position, duration, and playback rate.
- 🔧 **Native APIs**: Uses MediaSession API on Android and MPNowPlayingInfoCenter on iOS for the best possible integration.
- 🤝 **Compatibility**: Works with any playback inside the web view, such as HTML5 `<audio>` and `<video>` elements.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Media Session plugin is typically used in apps that play media and want to integrate with the operating system's media controls, for example:

- **Music streaming apps**: Display the current track's title, artist, album, and artwork on the lock screen and respond to play, pause, and track change actions.
- **Podcast and audiobook players**: Let users seek forward and backward with configurable seek offsets and display the current playback position and duration.
- **Video call apps**: Handle the microphone toggle, camera toggle, and hang up actions on the Web.
- **Presentation apps**: Respond to the previous and next slide actions on the Web.

## Compatibility

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

## Demo

| Android | iOS | Web |
| ------- | --- | --- |
|         |     |     |

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-media-session` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-media-session
npx cap sync
```

### Android

#### 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:

- `$androidMediaVersion` version of `androidx.media:media` (default: `1.7.1`)

## Configuration

These configuration options are available:

| Prop                  | Type     | Description                                                                                                                                                                                                                                                                       | Default                                                | Since |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----- |
| **nextTrackIcon**     | `string` | The name of the drawable resource to use as the icon for the next track action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.     | `"ic_media_next"` (Android built-in icon)              | 8.4.0 |
| **pauseIcon**         | `string` | The name of the drawable resource to use as the icon for the pause action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.          | `"ic_media_pause"` (Android built-in icon)             | 8.4.0 |
| **playIcon**          | `string` | The name of the drawable resource to use as the icon for the play action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.           | `"ic_media_play"` (Android built-in icon)              | 8.4.0 |
| **previousTrackIcon** | `string` | The name of the drawable resource to use as the icon for the previous track action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used. | `"ic_media_previous"` (Android built-in icon)          | 8.4.0 |
| **seekBackwardIcon**  | `string` | The name of the drawable resource to use as the icon for the seek backward action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.  | `"ic_media_rew"` (Android built-in icon)               | 8.4.0 |
| **seekForwardIcon**   | `string` | The name of the drawable resource to use as the icon for the seek forward action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.   | `"ic_media_ff"` (Android built-in icon)                | 8.4.0 |
| **smallIcon**         | `string` | The name of the drawable resource to use as the small icon in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.                         | `"ic_media_play"` (Android built-in icon)              | 8.1.0 |
| **stopIcon**          | `string` | The name of the drawable resource to use as the icon for the stop action in the media notification. Only available on Android. The resource name should not include the `R.drawable.` prefix or file extension. If the resource is not found, the default icon is used.           | `"ic_menu_close_clear_cancel"` (Android built-in icon) | 8.4.0 |

### Examples

In `capacitor.config.ts`:

```
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    MediaSession: {
      smallIcon: 'ic_notification',
    },
  },
};

export default config;
```

In `capacitor.config.json`:

```
{
  "plugins": {
    "MediaSession": {
      "smallIcon": "ic_notification"
    }
  }
}
```

### Android Custom Icon Setup

To use custom notification icons on Android:

1. Add your icons to `android/app/src/main/res/drawable/` (e.g., `ic_notification.png`)

1. Icons should be single-color white with transparent background for best display

1. Can use density-specific folders (`drawable-mdpi`, `drawable-hdpi`, etc.)

1. Configure the plugin in `capacitor.config.ts`:

   ```
   const config: CapacitorConfig = {
     plugins: {
       MediaSession: {
         smallIcon: 'ic_notification',  // Matches ic_notification.png
         seekBackwardIcon: 'ic_seek_backward_15',  // Matches ic_seek_backward_15.png
         seekForwardIcon: 'ic_seek_forward_15',  // Matches ic_seek_forward_15.png
       },
     },
   };
   ```

1. Run: `npx cap sync`

Note that the action icons (e.g. `playIcon`, `seekForwardIcon`) only affect the media notification on Android. On iOS, the playback controls on the lock screen and in the Control Center are rendered by the operating system and cannot be customized.

## Usage

The following examples show how to display track metadata, register handlers for media actions, update the playback and position state, listen for media session actions, and unregister handlers and remove listeners, using an HTML5 `<audio>` element for the actual audio playback.

### Display metadata about the current track

Set the title, artist, album, and artwork that the operating system displays on the lock screen and in notifications. Note that the `artwork` option is only available on iOS and Web:

```
import { MediaSession } from '@capawesome-team/capacitor-media-session';

const setMetadata = async () => {
  await MediaSession.setMetadata({
    title: 'Test Song',
    artist: 'My Awesome Artist',
    album: 'My Awesome Album',
    artwork: [
      {
        src: 'https://example.com/cover-96x96.png',
        sizes: '96x96',
        type: 'image/png',
      },
      {
        src: 'https://example.com/cover-512x512.png',
        sizes: '512x512',
        type: 'image/png',
      },
    ],
  });
};
```

### Register handlers for media actions

Register a handler for each media session action you want to support. The media session only responds to an action if a handler is registered for it:

```
import { MediaSession, MediaSessionAction } from '@capawesome-team/capacitor-media-session';

const registerActions = async () => {
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.Play
  });
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.Pause
  });
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.SeekBackward
  });
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.SeekForward
  });
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.SeekTo
  });
  await MediaSession.registerActionHandler({
    action: MediaSessionAction.Stop
  });
};
```

### Update the playback state

Tell the operating system whether media is currently playing, paused, or stopped so that the media controls reflect the correct state:

```
import { MediaSession, MediaSessionPlaybackState } from '@capawesome-team/capacitor-media-session';

const setPlaybackState = async () => {
  await MediaSession.setPlaybackState({
    playbackState: MediaSessionPlaybackState.Playing,
  });
};
```

### Update the position state

Report the duration, playback rate, and current position of the media in seconds so that the operating system can display a progress bar:

```
import { MediaSession } from '@capawesome-team/capacitor-media-session';

const setPositionState = async () => {
  await MediaSession.setPositionState({
    duration: 180,
    playbackRate: 1.0,
    position: 30,
  });
};
```

### Listen for media session actions

Add an `action` event listener to react to the registered actions, for example when the user presses a hardware media key or a button on the lock screen:

```
import { MediaSession, MediaSessionAction, MediaSessionPlaybackState } from '@capawesome-team/capacitor-media-session';

const audio = new Audio('https://example.com/audio.mp3');

const addActionListener = () => {
  MediaSession.addListener('action', async (event) => {
    switch (event.action) {
      case MediaSessionAction.Play:
        await audio.play();
        await MediaSession.setPlaybackState({
          playbackState: MediaSessionPlaybackState.Playing,
        });
        break;
      case MediaSessionAction.Pause:
        audio.pause();
        await MediaSession.setPlaybackState({
          playbackState: MediaSessionPlaybackState.Paused,
        });
        break;
      case MediaSessionAction.SeekBackward: {
        const offset = event.seekOffset ?? 10;
        audio.currentTime = Math.max(0, audio.currentTime - offset);
        break;
      }
      case MediaSessionAction.SeekForward: {
        const offset = event.seekOffset ?? 10;
        audio.currentTime = Math.min(audio.duration, audio.currentTime + offset);
        break;
      }
      case MediaSessionAction.SeekTo:
        if (event.seekTime !== undefined) {
          audio.currentTime = event.seekTime;
        }
        break;
      case MediaSessionAction.Stop:
        audio.pause();
        audio.currentTime = 0;
        await MediaSession.setPlaybackState({
          playbackState: MediaSessionPlaybackState.None,
        });
        break;
    }
  });
};
```

### Unregister action handlers and remove listeners

Make sure to unregister action handlers when they are no longer needed and remove your event listeners:

```
import { MediaSession, MediaSessionAction } from '@capawesome-team/capacitor-media-session';

const removeActionListener = async () => {
  await MediaSession.unregisterActionHandler({
    action: MediaSessionAction.Play
  });
  await MediaSession.unregisterActionHandler({
    action: MediaSessionAction.Pause
  });
  await MediaSession.removeAllListeners();
};
```

## API

- [`registerActionHandler(...)`](#registeractionhandler)
- [`setCameraActive(...)`](#setcameraactive)
- [`setMetadata(...)`](#setmetadata)
- [`setMicrophoneActive(...)`](#setmicrophoneactive)
- [`setPlaybackState(...)`](#setplaybackstate)
- [`setPositionState(...)`](#setpositionstate)
- [`setSeekOffset(...)`](#setseekoffset)
- [`unregisterActionHandler(...)`](#unregisteractionhandler)
- [`addListener('action', ...)`](#addlisteneraction-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### registerActionHandler(...)

```
registerActionHandler(options: RegisterActionHandlerOptions) => Promise<void>
```

Register a handler for a media session action.

If the action handler is registered, the media session will respond to the action by calling the `action` event listener. If the action handler is not registered, the media session will not respond to the action.

Make sure to unregister the action handler when it is no longer needed.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `RegisterActionHandlerOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setCameraActive(...)

```
setCameraActive(options: SetCameraActiveOptions) => Promise<void>
```

Set the camera active state.

Only available on Web.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetCameraActiveOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setMetadata(...)

```
setMetadata(options: SetMetadataOptions) => Promise<void>
```

Set the metadata for the media session.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetMetadataOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setMicrophoneActive(...)

```
setMicrophoneActive(options: SetMicrophoneActive) => Promise<void>
```

Set the microphone active state.

Only available on Web.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SetMicrophoneActive` |

**Since:** 0.0.1

______________________________________________________________________

### setPlaybackState(...)

```
setPlaybackState(options: SetPlaybackStateOptions) => Promise<void>
```

Set the playback state.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetPlaybackStateOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setPositionState(...)

```
setPositionState(options: SetPositionStateOptions) => Promise<void>
```

Set the position state.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetPositionStateOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setSeekOffset(...)

```
setSeekOffset(options: SetSeekOffsetOptions) => Promise<void>
```

Set the seek offset for the `SeekForward` and `SeekBackward` actions.

The offset controls both the value emitted in the `action` event's `seekOffset` property and the offset displayed by the OS (e.g., the number badge on the iOS lock-screen skip button).

Can be called at any time; the new offset is applied immediately.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetSeekOffsetOptions` |

**Since:** 8.3.0

______________________________________________________________________

### unregisterActionHandler(...)

```
unregisterActionHandler(options: UnregisterActionHandlerOptions) => Promise<void>
```

Unregister a handler for a media session action.

If the action handler is unregistered, the media session will no longer respond to the action and the `action` event listener will no longer be called for the specific action.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `UnregisterActionHandlerOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('action', ...)

```
addListener(eventName: 'action', listenerFunc: (event: ActionEvent) => void) => Promise<PluginListenerHandle>
```

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'action'`                     |
| **`listenerFunc`** | `(event: ActionEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### RegisterActionHandlerOptions

| Prop         | Type                 | Description           | Since |
| ------------ | -------------------- | --------------------- | ----- |
| **`action`** | `MediaSessionAction` | The action to handle. | 0.0.1 |

#### SetCameraActiveOptions

| Prop         | Type      | Description                          | Since |
| ------------ | --------- | ------------------------------------ | ----- |
| **`active`** | `boolean` | Whether or not the camera is active. | 0.0.1 |

#### SetMetadataOptions

| Prop          | Type                     | Description                                        | Since |
| ------------- | ------------------------ | -------------------------------------------------- | ----- |
| **`album`**   | `string`                 |                                                    | 0.0.1 |
| **`artist`**  | `string`                 |                                                    | 0.0.1 |
| **`artwork`** | `MediaMetadataArtwork[]` | Only the first artwork is used on Android and iOS. | 0.0.1 |
| **`title`**   | `string`                 |                                                    | 0.0.1 |

#### MediaMetadataArtwork

| Prop        | Type     | Description                                                 | Since |
| ----------- | -------- | ----------------------------------------------------------- | ----- |
| **`sizes`** | `string` | The size of the artwork.                                    | 0.0.1 |
| **`src`**   | `string` | The URL from which the user agent fetches the image's data. | 0.0.1 |
| **`type`**  | `string` | The MIME type hint for the user agent.                      | 0.0.1 |

#### SetMicrophoneActive

| Prop         | Type      | Description                              | Since |
| ------------ | --------- | ---------------------------------------- | ----- |
| **`active`** | `boolean` | Whether or not the microphone is active. | 0.0.1 |

#### SetPlaybackStateOptions

| Prop                | Type                        | Description                | Since |
| ------------------- | --------------------------- | -------------------------- | ----- |
| **`playbackState`** | `MediaSessionPlaybackState` | The playback state to set. | 0.0.1 |

#### SetPositionStateOptions

| Prop               | Type     | Description                                   | Since |
| ------------------ | -------- | --------------------------------------------- | ----- |
| **`duration`**     | `number` | The duration of the media in seconds.         | 0.0.1 |
| **`playbackRate`** | `number` | The playback rate of the media.               | 0.0.1 |
| **`position`**     | `number` | The current position of the media in seconds. | 0.0.1 |

#### SetSeekOffsetOptions

| Prop                     | Type     | Description                                                                                                                | Default | Since |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`seekBackwardOffset`** | `number` | The offset in seconds for the `SeekBackward` action. Must be greater than `0`. If not provided, the current value is kept. | `10`    | 8.3.0 |
| **`seekForwardOffset`**  | `number` | The offset in seconds for the `SeekForward` action. Must be greater than `0`. If not provided, the current value is kept.  | `10`    | 8.3.0 |

#### UnregisterActionHandlerOptions

| Prop         | Type                 | Description               | Since |
| ------------ | -------------------- | ------------------------- | ----- |
| **`action`** | `MediaSessionAction` | The action to unregister. | 0.0.1 |

#### PluginListenerHandle

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

#### ActionEvent

| Prop             | Type                 | Description                                | Since |
| ---------------- | -------------------- | ------------------------------------------ | ----- |
| **`action`**     | `MediaSessionAction` | The action that was handled.               | 0.0.1 |
| **`fastSeek`**   | `boolean`            | Whether or not the action was a fast seek. | 0.0.1 |
| **`seekOffset`** | `number`             | The offset in seconds to seek to.          | 0.0.1 |
| **`seekTime`**   | `number`             | The time in seconds to seek to.            | 0.0.1 |

### Enums

#### MediaSessionAction

| Members                     | Value                        | Description            | Since |
| --------------------------- | ---------------------------- | ---------------------- | ----- |
| **`Play`**                  | `'PLAY'`                     |                        | 0.0.1 |
| **`Pause`**                 | `'PAUSE'`                    |                        | 0.0.1 |
| **`SeekBackward`**          | `'SEEK_BACKWARD'`            |                        | 0.0.1 |
| **`SeekForward`**           | `'SEEK_FORWARD'`             |                        | 0.0.1 |
| **`PreviousTrack`**         | `'PREVIOUS_TRACK'`           |                        | 0.0.1 |
| **`NextTrack`**             | `'NEXT_TRACK'`               |                        | 0.0.1 |
| **`SkipAd`**                | `'SKIP_AD'`                  | Only available on Web. | 0.0.1 |
| **`Stop`**                  | `'STOP'`                     |                        | 0.0.1 |
| **`SeekTo`**                | `'SEEK_TO'`                  |                        | 0.0.1 |
| **`ToggleMicrophone`**      | `'TOGGLE_MICROPHONE'`        | Only available on Web. | 0.0.1 |
| **`ToggleCamera`**          | `'TOGGLE_CAMERA'`            | Only available on Web. | 0.0.1 |
| **`ToggleScreenShare`**     | `'TOGGLE_SCREEN_SHARE'`      | Only available on Web. | 0.0.1 |
| **`HangUp`**                | `'HANG_UP'`                  | Only available on Web. | 0.0.1 |
| **`PreviousSlide`**         | `'PREVIOUS_SLIDE'`           | Only available on Web. | 0.0.1 |
| **`NextSlide`**             | `'NEXT_SLIDE'`               | Only available on Web. | 0.0.1 |
| **`EnterPictureInPicture`** | `'ENTER_PICTURE_IN_PICTURE'` | Only available on Web. | 0.0.1 |
| **`VoiceActivity`**         | `'VOICE_ACTIVITY'`           | Only available on Web. | 0.0.1 |

#### MediaSessionPlaybackState

| Members       | Value       | Since |
| ------------- | ----------- | ----- |
| **`None`**    | `'NONE'`    | 0.0.1 |
| **`Paused`**  | `'PAUSED'`  | 0.0.1 |
| **`Playing`** | `'PLAYING'` | 0.0.1 |

## FAQ

### How do I show playback controls on the lock screen?

Set the metadata for the current track using `setMetadata`, register handlers for the actions you want to support using `registerActionHandler`, and update the playback state using `setPlaybackState`. The plugin uses the MediaSession API on Android and MPNowPlayingInfoCenter on iOS, so the operating system takes care of displaying the controls on the lock screen and in notifications. See the [usage examples](#usage) above for details.

### Why is the artwork not displayed on Android?

The `artwork` option of the `setMetadata` method is only available on iOS and Web. On Android, you can configure the notification icon instead using the `smallIcon` configuration option.

### Can I customize the notification icon on Android?

Yes, use the `smallIcon` configuration option to set the name of a drawable resource from your app's `res/drawable` directory. The icon should be single-color white with a transparent background for the best display. If the resource is not found, the default icon is used. See the [Configuration](#configuration) section for details.

### Can I customize the playback control icons?

On Android, yes. Use the configuration options `playIcon`, `pauseIcon`, `previousTrackIcon`, `nextTrackIcon`, `seekBackwardIcon`, `seekForwardIcon` and `stopIcon` to set the name of a drawable resource from your app's `res/drawable` directory for each action button in the media notification (e.g. a custom 15 seconds seek icon). If a resource is not found, the default icon is used. On iOS, this is not possible because the playback controls on the lock screen and in the Control Center are rendered by the operating system. See the [Configuration](#configuration) section for details.

### Can I use this plugin together with the Audio Player plugin?

No, this is not recommended. The [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) plugin provides a built-in media session integration (see its `metadata` option) that handles the media controls natively, without a round trip through the web view. This is more reliable, especially when the web view is suspended while the app is in the background. Use this plugin only for playback that runs inside the web view, such as HTML5 `<audio>` and `<video>` elements.

### Why does the media session not respond to certain actions?

The media session only responds to an action if a handler was registered for it using `registerActionHandler`. Also note that some actions such as `SkipAd`, `ToggleMicrophone`, `ToggleCamera`, `ToggleScreenShare`, `HangUp`, `PreviousSlide`, `NextSlide`, `EnterPictureInPicture` and `VoiceActivity` are only available on the Web.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play audio with background support.
- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses.
- [YouTube Player](https://capawesome.io/docs/sdks/capacitor/youtube-player/): Embed and control YouTube players, with lock-screen media controls via this plugin.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/media-session/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/media-session/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/media-session/LICENSE).

# Capacitor Navigation Bar Plugin

Capacitor plugin to set the background color and button style of the navigation bar.

## Features

The Capacitor Navigation Bar plugin offers one of the most complete solutions for customizing the Android navigation bar in Capacitor apps. Here are some of the key features:

- 🎨 **Background color**: Set the navigation bar background to any hex color or fully transparent.
- 🔘 **Button style**: Choose dark or light navigation bar buttons, or follow the system appearance.
- ➖ **Divider color**: Customize the navigation bar divider color on Android 9+.
- 👁️ **Visibility**: Hide or show the navigation bar on demand.
- ⚙️ **Configuration**: Apply defaults at app launch via the Capacitor configuration.
- 🤝 **Compatibility**: Works alongside the [Android Dark Mode Support](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/), [Android Edge-to-Edge Support](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/) and [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Navigation Bar plugin is typically used to make the Android system navigation bar blend in with the app's design, for example:

- **Brand theming**: Set the navigation bar background to your brand color so it matches the rest of your app.
- **Dark mode support**: Switch the navigation bar color and button style when the user toggles between light and dark themes.
- **Immersive experiences**: Hide the navigation bar for fullscreen content such as videos or games and show it again afterwards.
- **Consistent app launch**: Apply a default color, divider color, and button style at app launch via the Capacitor configuration.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Guides

- [Capacitor Edge-to-Edge & Safe Areas: The Complete Guide](https://capawesome.io/blog/capacitor-edge-to-edge-and-safe-areas-guide/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-navigation-bar` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-navigation-bar
npx cap sync
```

## Configuration

| Prop               | Type     | Description                                                                                                                                                        | Since       |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **`color`**        | `string` | The hexadecimal color to set as the background color of the navigation bar. Use `'transparent'` to make the navigation bar transparent. Only available on Android. | 8.0.0       |
| **`dividerColor`** | `string` | The hexadecimal color to set as the color of the navigation bar divider. Use `'transparent'` to hide the divider. Only available on Android (API level 28+).       | 8.0.0       |
| **`style`**        | \`'DARK' | 'LIGHT'                                                                                                                                                            | 'DEFAULT'\` |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "NavigationBar": {
      "color": "#ffffff",
      "dividerColor": "#d9d9d9",
      "style": "LIGHT"
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-navigation-bar" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    NavigationBar: {
      color: "#ffffff",
      dividerColor: "#d9d9d9",
      style: "LIGHT",
    },
  },
};

export default config;
```

## Usage

The following examples show how to set the navigation bar color and button style, read the current color and style, and hide and show the navigation bar.

### Set the navigation bar color

Set the background color of the navigation bar to any hexadecimal color, or pass `'transparent'` to make it fully transparent. Only available on Android:

```
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const setColor = async () => {
  await NavigationBar.setColor({ color: '#ffffff' });
};
```

### Set the button style

Choose dark or light navigation bar buttons, or use `Style.Default` to follow the current device appearance. Only available on Android:

```
import { NavigationBar, Style } from '@capawesome/capacitor-navigation-bar';

const setStyle = async () => {
  await NavigationBar.setStyle({ style: Style.Light });
};
```

### Read the current color and style

Get the current background color and button style of the navigation bar. Only available on Android:

```
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const getColor = async () => {
  const { color } = await NavigationBar.getColor();
  return color;
};

const getStyle = async () => {
  const { style } = await NavigationBar.getStyle();
  return style;
};
```

### Hide and show the navigation bar

Hide the navigation bar on demand, for example for fullscreen content, and show it again afterwards. Only available on Android:

```
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const hide = async () => {
  await NavigationBar.hide();
};

const show = async () => {
  await NavigationBar.show();
};
```

## API

- [`getColor()`](#getcolor)
- [`getStyle()`](#getstyle)
- [`hide()`](#hide)
- [`setColor(...)`](#setcolor)
- [`setStyle(...)`](#setstyle)
- [`show()`](#show)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getColor()

```
getColor() => Promise<GetColorResult>
```

Get the current background color of the navigation bar.

Only available on Android.

**Returns:** `Promise<GetColorResult>`

**Since:** 8.0.0

______________________________________________________________________

### getStyle()

```
getStyle() => Promise<GetStyleResult>
```

Get the current style of the navigation bar buttons.

Only available on Android.

**Returns:** `Promise<GetStyleResult>`

**Since:** 8.0.0

______________________________________________________________________

### hide()

```
hide() => Promise<void>
```

Hide the navigation bar.

Only available on Android.

**Since:** 8.0.0

______________________________________________________________________

### setColor(...)

```
setColor(options: SetColorOptions) => Promise<void>
```

Set the background color of the navigation bar.

Only available on Android.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetColorOptions` |

**Since:** 8.0.0

______________________________________________________________________

### setStyle(...)

```
setStyle(options: SetStyleOptions) => Promise<void>
```

Set the style of the navigation bar buttons.

Only available on Android.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetStyleOptions` |

**Since:** 8.0.0

______________________________________________________________________

### show()

```
show() => Promise<void>
```

Show the navigation bar.

Only available on Android.

**Since:** 8.0.0

______________________________________________________________________

### Interfaces

#### GetColorResult

| Prop        | Type     | Description                                                                                                 | Since |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- | ----- |
| **`color`** | `string` | The hexadecimal color of the navigation bar, or `'transparent'` if the navigation bar is fully transparent. | 8.0.0 |

#### GetStyleResult

| Prop        | Type    | Description                              | Since |
| ----------- | ------- | ---------------------------------------- | ----- |
| **`style`** | `Style` | The style of the navigation bar buttons. | 8.0.0 |

#### SetColorOptions

| Prop               | Type     | Description                                                                                                                                                  | Since |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`color`**        | `string` | The hexadecimal color to set as the background color of the navigation bar. Use `'transparent'` to make the navigation bar transparent.                      | 8.0.0 |
| **`dividerColor`** | `string` | The hexadecimal color to set as the color of the navigation bar divider. Use `'transparent'` to hide the divider. Only available on Android (API level 28+). | 8.0.0 |

#### SetStyleOptions

| Prop        | Type    | Description                              | Since |
| ----------- | ------- | ---------------------------------------- | ----- |
| **`style`** | `Style` | The style of the navigation bar buttons. | 8.0.0 |

### Enums

#### Style

| Members       | Value       | Description                                  | Since |
| ------------- | ----------- | -------------------------------------------- | ----- |
| **`Dark`**    | `'DARK'`    | Light icons on a dark background.            | 8.0.0 |
| **`Default`** | `'DEFAULT'` | Resolved from the current device appearance. | 8.0.0 |
| **`Light`**   | `'LIGHT'`   | Dark icons on a light background.            | 8.0.0 |

## FAQ

### Why are the `setColor` and `setStyle` methods not working on Android 15+?

Starting with Android 15, the system enforces [edge-to-edge display](https://developer.android.com/develop/ui/views/layout/edge-to-edge) by default. In this mode the navigation bar is fully transparent and `Window.setNavigationBarColor` becomes a no-op, so setting the color through this plugin has no visible effect. If your app targets Android 15+ and you want to color the navigation bar area, use the [`@capawesome/capacitor-android-edge-to-edge-support`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/android-edge-to-edge-support) plugin, which paints an overlay behind the navigation bar.

### Why is this plugin not available on iOS?

iOS does not have a system navigation bar that can be customized in the same way as on Android. All methods of this plugin are therefore unimplemented on iOS and reject with an error.

### How do I make the navigation bar transparent?

Pass `'transparent'` as the color to the `setColor` method or use it as the `color` value in the [Capacitor configuration](#configuration). You can also pass `'transparent'` as the `dividerColor` to hide the navigation bar divider.

### Can I apply a color and style at app launch?

Yes, you can define the `color`, `dividerColor`, and `style` properties in the `NavigationBar` section of your Capacitor configuration file. The plugin applies these defaults when the app launches, so you don't have to call `setColor` or `setStyle` manually. See the [Configuration](#configuration) section for examples.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Dark Mode Support](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/): Seamless dark mode support for Android with `prefers-color-scheme` compatibility.
- [Android Edge-to-Edge Support](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/): Support edge-to-edge display on Android, including setting the background color of the status bar and navigation bar.
- [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/): Hide and show the home indicator on iOS.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/navigation-bar/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/navigation-bar/LICENSE).

# Capacitor Network Plugin

Capacitor plugin to access network information.

## Features

The Capacitor Network plugin is one of the most complete network information solutions for Capacitor apps. Here are some of the key features:

- 📶 **Network status**: Read whether the device is connected and how (Wi-Fi, cellular, ethernet, VPN).
- 🌍 **Internet reachability**: Detect whether the connection has verified access to the internet (Android).
- 💸 **Data saving & cost**: Detect whether the connection is constrained (Data Saver or Low Data Mode) or expensive (metered).
- 🛰️ **Satellite networks**: Detect satellite transport on Android 15+ and ultra-constrained connections on iOS 26+.
- ✈️ **Airplane mode**: Read whether the airplane mode is enabled (Android).
- 👂 **Change events**: Listen for changes to the network status.
- 🌐 **Web support**: Read the network status on the web.
- 🤝 **Compatibility**: Works alongside the [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Network plugin is typically used whenever an app needs to react to the device's connectivity, for example:

- **Offline detection**: Show an offline banner or disable network-dependent features when the connection is lost.
- **Conditional downloads**: Only download large files when the device is connected via Wi-Fi instead of a cellular network.
- **Reliable syncing**: On Android, check whether the connection has verified internet access before starting a sync, avoiding false positives caused by captive portals or VPNs.
- **Airplane mode hints**: On Android, detect that airplane mode is enabled and inform the user why no connection is available.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [How to Detect the Network Status in Capacitor](https://capawesome.io/blog/how-to-detect-the-network-status-in-a-capacitor-app/): Check the connection type, listen for changes, and handle offline and metered connections.
- [How to Detect Satellite Networks in Capacitor](https://capawesome.io/blog/how-to-detect-satellite-networks-in-a-capacitor-app/): Detect satellite and ultra-constrained networks on Android 15+ and iOS 26 and adapt to limited bandwidth.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-network` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-network
npx cap sync
```

On **Android**, the plugin declares the [`ACCESS_NETWORK_STATE`](https://developer.android.com/reference/android/Manifest.permission#ACCESS_NETWORK_STATE) permission in its manifest, so no additional configuration is required.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get the current network status, check whether airplane mode is enabled, and listen for changes to the network status.

### Get the current network status

Read whether the device is currently connected, the type of the connection (e.g. Wi-Fi or cellular) and, on Android, whether the connection has verified access to the internet:

```
import { Network } from '@capawesome/capacitor-network';

const getStatus = async () => {
  const status = await Network.getStatus();
  return status;
};
```

### Detect satellite networks

Read whether the device is connected via a satellite network. Only available on Android:

```
import { ConnectionType, Network } from '@capawesome/capacitor-network';

const isSatellite = async () => {
  const { connectionType } = await Network.getStatus();
  return connectionType === ConnectionType.Satellite;
};
```

Android only uses constrained satellite networks for apps that identify themselves as optimized for them. If your app is optimized for extremely limited bandwidth and variable latency, add the following element to the `application` element in your `AndroidManifest.xml`:

```
<meta-data
  android:name="android.telephony.PROPERTY_SATELLITE_DATA_OPTIMIZED"
  android:value="PACKAGE_NAME"
/>
```

Replace `PACKAGE_NAME` with your app's package name. This plugin does not add this element automatically, because each app must decide whether it is suitable for constrained satellite access. Push notifications must additionally be sent with the `bandwidth_constrained_ok` flag to be delivered on such a network. See [Constrained satellite networks](https://developer.android.com/develop/connectivity/satellite/constrained-networks) for more information.

On **iOS**, carrier-provided satellite connections are reported as `CELLULAR` with `ultraConstrained` set to `true`, because Apple does not expose satellite as a connection type.

### Detect ultra-constrained networks

Read whether the connection is severely limited in bandwidth, such as a carrier-provided satellite network. Only available on Android and iOS 26+:

```
import { Network } from '@capawesome/capacitor-network';

const isUltraConstrained = async () => {
  const { ultraConstrained } = await Network.getStatus();
  return ultraConstrained;
};
```

On **Android**, this is `true` on satellite networks and on networks that the system reports as bandwidth-constrained. Satellite networks are always reported as ultra-constrained, while bandwidth-constraint detection requires Android 16+ (API level 36) or [U Extensions](https://developer.android.com/guide/sdk-extensions) 16+, which can be present on eligible devices running Android 14 or later.

On **iOS**, detecting this state requires no entitlement. However, if your app wants to transfer data over such a network, it must allow this per request (see [`allowsUltraConstrainedNetworkAccess`](https://developer.apple.com/documentation/foundation/urlrequest/allowsultraconstrainednetworkaccess)) and may need the [`com.apple.developer.networking.carrier-constrained.appcategory`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.networking.carrier-constrained.appcategory) entitlement to be allowed on all carriers. This plugin neither adds entitlements nor modifies your `URLSession` or `NWParameters` configuration. See [Configuring your app for ultra-constrained networks](https://developer.apple.com/documentation/bundleresources/configuring-your-app-for-ultra-constrained-networks) for more information.

### Check whether airplane mode is enabled

Read whether the airplane mode is currently enabled. Only available on Android:

```
import { Network } from '@capawesome/capacitor-network';

const isAirplaneModeEnabled = async () => {
  const { enabled } = await Network.isAirplaneModeEnabled();
  return enabled;
};
```

### Listen for changes to the network status

Get notified whenever the network status of the device changes. The device is only observed while at least one listener is attached:

```
import { Network } from '@capawesome/capacitor-network';

const addNetworkStatusChangeListener = async () => {
  await Network.addListener('networkStatusChange', status => {
    console.log('Network status changed:', status);
  });
};
```

When you no longer need updates, remove all listeners:

```
import { Network } from '@capawesome/capacitor-network';

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

## API

- [`getStatus()`](#getstatus)
- [`isAirplaneModeEnabled()`](#isairplanemodeenabled)
- [`addListener('networkStatusChange', ...)`](#addlistenernetworkstatuschange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getStatus()

```
getStatus() => Promise<GetStatusResult>
```

Get the current network status of the device.

Only available on Android, iOS and Web.

**Returns:** `Promise<GetStatusResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAirplaneModeEnabled()

```
isAirplaneModeEnabled() => Promise<IsAirplaneModeEnabledResult>
```

Get whether the airplane mode is currently enabled.

Only available on Android.

**Returns:** `Promise<IsAirplaneModeEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('networkStatusChange', ...)

```
addListener(eventName: 'networkStatusChange', listenerFunc: (event: GetStatusResult) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the network status of the device.

The device is only observed while at least one listener is attached.

Only available on Android, iOS and Web.

| Param              | Type                               |
| ------------------ | ---------------------------------- |
| **`eventName`**    | `'networkStatusChange'`            |
| **`listenerFunc`** | `(event: GetStatusResult) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetStatusResult

| Prop                    | Type             | Description                                             | Since                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------- | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`connected`**         | `boolean`        | Whether the device is currently connected to a network. | 0.1.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **`connectionType`**    | `ConnectionType` | The type of the currently active network connection.    | 0.1.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **`internetReachable`** | \`boolean        | null\`                                                  | Whether the active network connection has verified access to the internet. This is `null` on platforms that cannot validate internet access (iOS and Web), where connectivity does not guarantee reachability. Only available on Android.                                                                                                                                                                                                                                            |
| **`constrained`**       | \`boolean        | null\`                                                  | Whether the active network connection is subject to data saving restrictions, such as Data Saver on Android or Low Data Mode on iOS. This is `false` if the device is not connected to a network and `null` on browsers that do not expose this information.                                                                                                                                                                                                                         |
| **`expensive`**         | \`boolean        | null\`                                                  | Whether the active network connection is considered expensive, for example a metered Wi-Fi or cellular network. This is `false` if the device is not connected to a network and `null` on platforms that cannot determine the cost of the connection (Web).                                                                                                                                                                                                                          |
| **`ultraConstrained`**  | \`boolean        | null\`                                                  | Whether the active network connection is severely limited in bandwidth, such as a carrier-provided satellite network. This is `false` if the device is not connected to a network and `null` on platforms that cannot determine this (Web and iOS below 26). On Android, satellite networks are always reported as ultra-constrained. Detecting other bandwidth-constrained networks requires Android 16+ (API level 36) or U Extensions 16+. Only available on Android and iOS 26+. |

#### IsAirplaneModeEnabledResult

| Prop          | Type      | Description                                     | Since |
| ------------- | --------- | ----------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether the airplane mode is currently enabled. | 0.1.0 |

#### PluginListenerHandle

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

### Enums

#### ConnectionType

| Members         | Value         | Description                                                                 | Since |
| --------------- | ------------- | --------------------------------------------------------------------------- | ----- |
| **`Cellular`**  | `'CELLULAR'`  | The device is connected via a cellular network.                             | 0.1.0 |
| **`Ethernet`**  | `'ETHERNET'`  | The device is connected via a wired ethernet network.                       | 0.1.0 |
| **`None`**      | `'NONE'`      | The device is not connected to any network.                                 | 0.1.0 |
| **`Satellite`** | `'SATELLITE'` | The device is connected via a satellite network. Only available on Android. | 0.1.2 |
| **`Unknown`**   | `'UNKNOWN'`   | The type of the network connection could not be determined.                 | 0.1.0 |
| **`Vpn`**       | `'VPN'`       | The device is connected via a virtual private network (VPN).                | 0.1.0 |
| **`Wifi`**      | `'WIFI'`      | The device is connected via a Wi-Fi network.                                | 0.1.0 |

## Network Information

Keep the following platform differences in mind when accessing network information:

- **Android**: The network status is read from the [`ConnectivityManager`](https://developer.android.com/reference/android/net/ConnectivityManager). The `internetReachable` property reflects the [`NET_CAPABILITY_VALIDATED`](https://developer.android.com/reference/android/net/NetworkCapabilities#NET_CAPABILITY_VALIDATED) capability, which fixes false positives when a VPN or captive portal is active.
- **iOS**: The network status is read from the [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor) of the Network framework. The `internetReachable` property is always `null` because iOS cannot distinguish validated internet access from mere connectivity. VPN connections are reported as `UNKNOWN`. The `isAirplaneModeEnabled()` method is not available because there is no public API for it.
- **Web**: The network status is read from [`navigator.onLine`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) and the [Network Information API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) (where supported). The `internetReachable` property is always `null`. The `isAirplaneModeEnabled()` method is not available.

## FAQ

### How is this plugin different from other similar plugins?

It reports connectivity and the connection type (Wi-Fi, cellular, ethernet, or VPN) on Android, iOS, and the web, and on Android it adds verified internet reachability that avoids false positives from captive portals or VPNs, plus an airplane-mode check. You can read the status once or listen for change events, with the device observed only while a listener is attached, all through a fully typed API with typed connection-type enums. It supports both CocoaPods and Swift Package Manager on iOS, is honest about platform limits by returning `null` where reachability cannot be validated, and is actively maintained against the latest Capacitor and OS versions.

### What is the difference between `connected` and `internetReachable`?

The `connected` property tells you whether the device is connected to any network, while `internetReachable` tells you whether that connection has verified access to the internet. A device can be connected to a network without actually reaching the internet, for example behind a captive portal or when a VPN is active. The `internetReachable` property is only available on Android, where it reflects the `NET_CAPABILITY_VALIDATED` capability of the connection.

### Why is `internetReachable` always `null` on iOS and Web?

iOS and the Web platform cannot distinguish validated internet access from mere network connectivity, so the plugin returns `null` instead of a potentially misleading value. On these platforms, being connected to a network does not guarantee that the internet is reachable. See the [Network Information](#network-information) section for the platform-specific details.

### What is the difference between the `SATELLITE` connection type and `ultraConstrained`?

The `SATELLITE` connection type tells you what the connection is, while `ultraConstrained` tells you that it is severely limited in bandwidth. Satellite is only reported as a connection type on Android, because iOS exposes this condition as a property of the connection instead. The two do not always match: a satellite network is not necessarily reported as bandwidth-constrained, and a bandwidth-constrained network is not necessarily a satellite network.

### Can I check whether airplane mode is enabled on iOS or Web?

No, the `isAirplaneModeEnabled()` method is only available on Android. On iOS, there is no public API to read the airplane mode state, and the Web platform does not expose this information either.

### Do I need any permissions to use this plugin?

No, the plugin works without any additional configuration. On Android, the plugin already declares the required `ACCESS_NETWORK_STATE` permission in its own manifest, see the [Installation](#installation) section.

### Why is a VPN connection reported as `UNKNOWN` on iOS?

On iOS, the network status is read from the `NWPathMonitor` of the Network framework, and VPN connections are reported as `UNKNOWN`. The `VPN` connection type is only reported on platforms that can detect it, such as Android. See the [Network Information](#network-information) section for more platform differences.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/): Access battery information of the device.
- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with Bluetooth Low Energy (BLE) devices in the central and peripheral role.
- [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/): Read, write, and emulate NFC tags with advanced features like HCE and raw command handling.
- [Sim](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information.
- [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/network/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/network/LICENSE).

# Capacitor NFC Plugin

Capacitor plugin for NFC tag reading, writing, and emulation. Supports Android, iOS, and Web with advanced features like HCE and raw command handling.

## Features

The Capacitor NFC plugin is one of the most complete NFC solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🔄 **NDEF**: Read and write NFC Data Exchange Format (NDEF) messages.
- 📳 **HCE**: Emulate an NFC card that other devices can interact with.
- ⌘ **Raw Commands**: Send raw commands to an NFC tag and receive the response.
- 🛠️ **Utils**: Utility functions to make your life easier.
- ⚔️ **Battle-Tested**: Used in more than 500 projects.
- 📚 **Documentation**: Comprehensive documentation to help you get started.
- 🤝 **Compatibility**: Works alongside the [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/), [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/) and [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The NFC plugin is typically used whenever an app needs to interact with NFC tags or readers, for example:

- **Inventory and asset tracking**: Scan NFC tags to read their identifiers and NDEF messages, for example to identify equipment or products.
- **Tag provisioning**: Write NDEF messages such as text or URI records to tags and optionally make them permanently read-only.
- **App launching**: Launch your app by scanning a tag containing a URI record, using an intent filter on Android or universal links on iOS.
- **Smartcard communication**: Exchange raw commands such as APDUs with tags and smartcards using the `transceive(...)` method.
- **Card emulation**: Emulate an NFC card on Android using Host Card Emulation (HCE) so that other devices can interact with it.
- **Tap-to-pair onboarding**: Read a nearby device's identifier from an NFC tag, then connect to it over [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/) — no manual scanning or pairing UI needed.

## 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     |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-nfc-demo).

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor NFC Plugin](https://capawesome.io/blog/announcing-the-capacitor-nfc-plugin/)
- [Exploring the Capacitor NFC API](https://capawesome.io/blog/exploring-the-capacitor-nfc-api/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-nfc` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-nfc
npx cap sync
```

### Android

#### Features

Add the following element to your `AndroidManifest.xml` before or after the `application` tag:

```
<uses-feature android:name="android.hardware.nfc" android:required="true" />
```

Set the `android:required` attribute to `true` if your app can't function, or isn't designed to function, when NFC is not available on the device. If your app can function without NFC, set the `android:required` attribute to `false`. This will allow your app to be installed on devices that do not support NFC.

#### Intent Filter

If you want to launch your app through an NFC tag, please take a look at the [Android documentation](https://developer.android.com/guide/topics/connectivity/nfc/nfc#dispatching). There you will find which changes you have to apply to your `AndroidManifest.xml` ([example](https://developer.android.com/guide/topics/connectivity/nfc/nfc#ndef-disc)).

#### Services

To be able to use Host Card Emulation (HCE), you also need to add the following service **inside** the `application` tag in your `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`):

```
<service android:name=".MyHostApduService" android:exported="true"
         android:permission="android.permission.BIND_NFC_SERVICE">
    <intent-filter>
        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE"/>
    </intent-filter>
    <meta-data android:name="android.nfc.cardemulation.host_apdu_service"
               android:resource="@xml/apduservice"/>
</service>
```

This meta-data tag points to an `apduservice.xml` file. The following is an example of such a file with a single AID group declaration containing two proprietary AIDs:

```
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
           android:description="@string/servicedesc"
           android:requireDeviceUnlock="false">
    <aid-group android:description="@string/aiddescription"
               android:category="other">
        <aid-filter android:name="F0010203040506"/>
        <aid-filter android:name="F0394148148100"/>
    </aid-group>
</host-apdu-service>
```

You can find more information about this in the [Android documentation](https://developer.android.com/develop/connectivity/nfc/hce#manifest-declaration).

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Entitlements

Ensure `Near Field Communication Tag Reading` and `NFC Scan` capabilities have been enabled in your application in Xcode. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

This will also create or update the `ios/App/App/App.entitlements` file. Make sure it contains the following key to allow reading NFC tags:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.nfc.readersession.formats</key>
    <array>
        <string>NDEF</string>
        <string>TAG</string>
    </array>
</dict>
</plist>
```

#### Privacy Descriptions

Add the `NFCReaderUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why the app needs to use NFC:

```
<key>NFCReaderUsageDescription</key>
<string>The app enables the reading and writing of various NFC tags.</string>
```

#### Universal Links

If you want to launch your app through an NFC tag, please take a look at the [Core NFC documentation](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032598). The NFC tag requires a [URI record](https://w3c.github.io/web-nfc/#uri-record) (see [`createNdefUriRecord(...)`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/nfc/docs/utils#createndefurirecord)) that must contain either a universal link (see [Deep Linking with Universal and App Links](https://capacitorjs.com/docs/guides/deep-links)) or a [supported URL scheme](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032600).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read, write, make read-only, erase, and format NFC tags, send raw commands, check NFC support and permissions, and use Host Card Emulation.

### Read an NFC tag

Start a scan session and listen for the `nfcTagScanned` event to receive the scanned tag. Only one session can be active at a time, so stop the session as soon as you are done. On iOS, starting a scan session triggers the NFC Reader Session alert:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const read = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      await Nfc.stopScanSession();
      resolve(event.nfcTag);
    });

    Nfc.startScanSession();
  });
};
```

### Write to an NFC tag

Create an NDEF record, for example with the `NfcUtils` class (see [Utils](#utils)), and write it to the tag from within the `nfcTagScanned` handler:

```
import { Nfc, NfcUtils } from '@capawesome-team/capacitor-nfc';

const createNdefTextRecord = () => {
  const utils = new NfcUtils();
  const { record } = utils.createNdefTextRecord({ text: 'Capacitor NFC Plugin' });
  return record;
};

const write = async () => {
  return new Promise((resolve) => {
    const record = createNdefTextRecord();

    Nfc.addListener('nfcTagScanned', async (event) => {
      await Nfc.write({ message: { records: [record] } });
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};
```

### Make an NFC tag read-only

Use the `makeReadOnly()` method to write-protect a tag. **Attention**: This is permanent and cannot be undone:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const makeReadOnly = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      await Nfc.makeReadOnly();
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};
```

### Erase or format an NFC tag

Use the `erase()` method to write an empty NDEF message to the tag, or the `format()` method to format the tag as NDEF first. The `format()` method is only available on Android:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const erase = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      await Nfc.erase();
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};

const format = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      await Nfc.format();
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};
```

### Send raw commands to an NFC tag

Use the `transceive(...)` method to send raw commands to the tag and receive the response. On Android, you must connect to the tag with `connect(...)` first and close the connection with `close()` afterwards. On iOS, pass the tag technology directly to `transceive(...)`. This method is only available on Android and iOS. The following example reads the signature of a tag:

```
import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc';
import { Capacitor } from '@capacitor/core';

const readSignature = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      if (Capacitor.getPlatform() === 'android') {
        // 1. Connect to the tag.
        await Nfc.connect({ techType: NfcTagTechType.NfcA }); 
        // 2. Send one or more commands to the tag and receive the response.
        const result = await Nfc.transceive({ data: [60, 0] });
        // 3. Close the connection to the tag.
        await Nfc.close();
        await Nfc.stopScanSession();
        resolve(result);
      } else {
        // 1. Send one or more commands to the tag and receive the response.
        const result = await Nfc.transceive({ techType: NfcTagTechType.NfcA, data: [60, 0] });
        await Nfc.stopScanSession();
        resolve(result);
      }
    });

    Nfc.startScanSession();
  });
};
```

### Check whether NFC is supported and enabled

Use the `isSupported()` method to check whether the device supports NFC and the `isEnabled()` method to check whether NFC is enabled:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const isSupported = async () => {
  const { nfc } = await Nfc.isSupported();
  return nfc;
};

const isEnabled = async () => {
  const { isEnabled } = await Nfc.isEnabled();
  return isEnabled;
};
```

### Open the NFC device settings

Open the NFC device settings so that the user can enable or disable NFC. Only available on Android:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const openSettings = async () => {
  await Nfc.openSettings();
};
```

### Check and request permissions

Checking and requesting permissions is only needed on Web. On Android and iOS, `granted` is always returned:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const checkPermissions = async () => {
  const { nfc } = await Nfc.checkPermissions();
  return nfc;
};

const requestPermissions = async () => {
  const { nfc } = await Nfc.requestPermissions();
  return nfc;
};
```

### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

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

### Advanced

#### HCE

Host Card Emulation (HCE) allows your device to emulate an NFC card that other devices can interact with. The first example below demonstrates how to send APDU commands from an NFC reader using the `transceive(...)` method:

```
import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc';
import { Capacitor } from '@capacitor/core';

const sendApduCommands = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      // Define APDU commands
      const selectApdu = [0x00, 0xA4, 0x04, 0x00, 0x07, 0xF0, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x00];
      const customApdu = [0x00, 0x01, 0x00, 0x00, 0x00];

      // Connect to the tag (Android only)
      if (Capacitor.getPlatform() === 'android') {
        await Nfc.connect({ techType: NfcTagTechType.IsoDep });
      }

      // Send SELECT APDU command
      const selectResponse = await Nfc.transceive({
        techType: NfcTagTechType.Iso7816,
        data: selectApdu
      });

      // Send custom APDU command
      const customResponse = await Nfc.transceive({
        techType: NfcTagTechType.Iso7816,
        data: customApdu
      });

      // Close the connection (Android only)
      if (Capacitor.getPlatform() === 'android') {
        await Nfc.close();
      }

      // Stop the scan session
      await Nfc.stopScanSession();
      resolve();
    });
    // Start the scan session
    Nfc.startScanSession();
  });
};
```

The second example below demonstrates how to respond to APDU commands sent by an NFC reader using the `commandReceived` event listener and the `respond(...)` method:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const respondToApduCommands = async () => {
  // Listen for incoming APDU commands
  Nfc.addListener('commandReceived', async (event) => {
    // Parse the incoming command
    const command = event.data;

    // Check if it's a SELECT command
    if (command[0] === 0x00 && command[1] === 0xA4 && command[2] === 0x04 && command[3] === 0x00) {
      // Respond with success status (0x9000)
      const response = [0x90, 0x00];
      await Nfc.respond({ data: response });
    }
    // Check for custom command
    else if (command[0] === 0x00 && command[1] === 0x01) {
      // Respond with custom data
      const response = [0x48, 0x65, 0x6C, 0x6C, 0x6F, 0x90, 0x00]; // "Hello" + success status
      await Nfc.respond({ data: response });
    }
    // Unknown command
    else {
      // Respond with error status (0x6D00 - Instruction not supported)
      const response = [0x6D, 0x00];
      await Nfc.respond({ data: response });
    }
  });
};
```

## API

- [`startScanSession(...)`](#startscansession)
- [`stopScanSession(...)`](#stopscansession)
- [`write(...)`](#write)
- [`respond(...)`](#respond)
- [`makeReadOnly()`](#makereadonly)
- [`erase()`](#erase)
- [`format()`](#format)
- [`transceive(...)`](#transceive)
- [`connect(...)`](#connect)
- [`close()`](#close)
- [`isAvailable()`](#isavailable)
- [`isSupported()`](#issupported)
- [`isEnabled()`](#isenabled)
- [`openSettings()`](#opensettings)
- [`getAntennaInfo()`](#getantennainfo)
- [`setAlertMessage(...)`](#setalertmessage)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('commandReceived', ...)`](#addlistenercommandreceived-)
- [`addListener('nfcLinkDeactivated', ...)`](#addlistenernfclinkdeactivated-)
- [`addListener('nfcTagScanned', ...)`](#addlistenernfctagscanned-)
- [`addListener('scanSessionCanceled', ...)`](#addlistenerscansessioncanceled-)
- [`addListener('scanSessionError', ...)`](#addlistenerscansessionerror-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### startScanSession(...)

```
startScanSession(options?: StartScanSessionOptions | undefined) => Promise<void>
```

Start a scan session. Only one session can be active at a time.

Stop the session as soon as you are done using `stopScanSession(...)`.

On iOS, this will trigger the NFC Reader Session alert.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `StartScanSessionOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopScanSession(...)

```
stopScanSession(options?: StopScanSessionOptions | undefined) => Promise<void>
```

Stop the active scan session.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `StopScanSessionOptions` |

**Since:** 0.0.1

______________________________________________________________________

### write(...)

```
write(options: WriteOptions) => Promise<void>
```

Write to a NFC tag.

This method must be called from within a `nfcTagScanned` handler.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `WriteOptions` |

**Since:** 0.0.1

______________________________________________________________________

### respond(...)

```
respond(options: RespondOptions) => Promise<void>
```

Send a response APDU back to the remote device.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `RespondOptions` |

**Since:** 6.3.0

______________________________________________________________________

### makeReadOnly()

```
makeReadOnly() => Promise<void>
```

Make a NFC tag readonly.

This method must be called from within a `nfcTagScanned` handler.

**Attention:** This is permanent and can not be undone.

**Since:** 0.0.1

______________________________________________________________________

### erase()

```
erase() => Promise<void>
```

Erase the NFC tag by writing an empty NDEF message.

This method must be called from within a `nfcTagScanned` handler.

**Since:** 0.3.0

______________________________________________________________________

### format()

```
format() => Promise<void>
```

Format the NFC tag as NDEF and write an empty NDEF message.

This method must be called from within a `nfcTagScanned` handler.

Only available on Android.

**Since:** 0.3.0

______________________________________________________________________

### transceive(...)

```
transceive(options: TransceiveOptions) => Promise<TransceiveResult>
```

Send raw command to the tag and receive the response.

This method must be called from within a `nfcTagScanned` handler.

On **Android**, the tag must be connected with `connect()` first.

⚠️ **Experimental:** This method could not be tested extensively yet. Please let us know if you discover any issues!

⚠️ **Attention**: A bad command can damage the tag forever. Please read the Android and iOS documentation linked below first.

More information on how to use this method on **Android**: https://bit.ly/3ywSkvT

More information on how to use this method on **iOS** with...

- ISO 15693-3: https://apple.co/3Lliaum
- FeliCa: https://apple.co/3LpvRs6

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `TransceiveOptions` |

**Returns:** `Promise<TransceiveResult>`

**Since:** 0.3.0

______________________________________________________________________

### connect(...)

```
connect(options: ConnectOptions) => Promise<void>
```

Connect to the tag and enable I/O operations.

This method must be called from within a `nfcTagScanned` handler.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ConnectOptions` |

**Since:** 6.0.0

______________________________________________________________________

### close()

```
close() => Promise<void>
```

Close the connection to the tag.

This method must be called from within a `nfcTagScanned` handler.

Only available on Android.

**Since:** 6.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Returns whether or not NFC is available.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 7.2.0

______________________________________________________________________

### isSupported()

```
isSupported() => Promise<IsSupportedResult>
```

Returns whether or not NFC is supported.

**Returns:** `Promise<IsSupportedResult>`

**Since:** 0.0.1

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Returns whether or not NFC is enabled.

On **iOS** and **Web**, this method reflects whether NFC reading is available on the device. iOS does not expose a global NFC on/off setting.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.0.1

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Opens the NFC device settings so that the user can enable or disable NFC.

Only available on Android.

**Since:** 0.0.1

______________________________________________________________________

### getAntennaInfo()

```
getAntennaInfo() => Promise<GetAntennaInfoResult>
```

Returns information regarding Nfc antennas on the device such as their relative positioning on the device.

Only available on Android.

**Returns:** `Promise<GetAntennaInfoResult>`

**Since:** 6.1.0

______________________________________________________________________

### setAlertMessage(...)

```
setAlertMessage(options: SetAlertMessageOptions) => Promise<void>
```

Set a custom message, which is displayed in the NFC Reader Session alert.

Only available on iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetAlertMessageOptions` |

**Since:** 6.2.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionResult>
```

Check permission for reading and writing NFC tags.

This method is only needed on Web. On Android and iOS, `granted` is always returned.

**Returns:** `Promise<PermissionResult>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionResult>
```

Request permission for reading and writing NFC tags.

This method is only needed on Web. On Android and iOS, `granted` is always returned.

**Returns:** `Promise<PermissionResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('commandReceived', ...)

```
addListener(eventName: 'commandReceived', listenerFunc: (event: CommandReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called whenever a NFC reader sends an Application Protocol Data Unit (APDU).

Only available on Android.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'commandReceived'`                     |
| **`listenerFunc`** | `(event: CommandReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.3.0

______________________________________________________________________

### addListener('nfcLinkDeactivated', ...)

```
addListener(eventName: 'nfcLinkDeactivated', listenerFunc: (event: NfcLinkDeactivatedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the NFC link has been deactivated or lost.

Only available on Android.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'nfcLinkDeactivated'`                     |
| **`listenerFunc`** | `(event: NfcLinkDeactivatedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.3.0

______________________________________________________________________

### addListener('nfcTagScanned', ...)

```
addListener(eventName: 'nfcTagScanned', listenerFunc: (event: NfcTagScannedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new NFC tag is scanned.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'nfcTagScanned'`                     |
| **`listenerFunc`** | `(event: NfcTagScannedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('scanSessionCanceled', ...)

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

Called when the scan session was canceled.

Only available on iOS.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'scanSessionCanceled'` |
| **`listenerFunc`** | `() => void`            |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('scanSessionError', ...)

```
addListener(eventName: 'scanSessionError', listenerFunc: (event: ScanSessionErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during the scan session.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'scanSessionError'`                     |
| **`listenerFunc`** | `(event: ScanSessionErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### StartScanSessionOptions

| Prop                    | Type               | Description                                                                                                                                                                                                  | Default                                            | Since |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ----- |
| **`alertMessage`**      | `string`           | A custom message, which is displayed in the NFC Reader Session alert. Only available on iOS.                                                                                                                 |                                                    | 0.0.1 |
| **`compatibilityMode`** | `boolean`          | Whether or not to use the [`NFCNDEFReaderSession`](https://developer.apple.com/documentation/corenfc/nfcndefreadersession). **Attention:** This mode only supports reading NDEF tags. Only available on iOS. | `false`                                            | 6.4.0 |
| **`techTypes`**         | `NfcTagTechType[]` | The NFC tag technologies to filter on in this session. Only available on Android.                                                                                                                            |                                                    | 0.0.1 |
| **`mimeTypes`**         | `string[]`         | Mime types to filter on in this session. Only available on Android.                                                                                                                                          |                                                    | 0.0.1 |
| **`pollingOptions`**    | `PollingOption[]`  | Type of tags to detect during a polling sequence. Only available on iOS.                                                                                                                                     | `[PollingOption.iso14443, PollingOption.iso15693]` | 0.2.0 |

#### StopScanSessionOptions

| Prop               | Type     | Description                                                                                        | Since |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------- | ----- |
| **`errorMessage`** | `string` | A custom error message, which is displayed in the NFC Reader Session alert. Only available on iOS. | 0.0.1 |

#### WriteOptions

| Prop          | Type          | Description                | Since |
| ------------- | ------------- | -------------------------- | ----- |
| **`message`** | `NdefMessage` | The NDEF message to write. | 0.0.1 |

#### NdefMessage

| Prop          | Type           | Description                      | Since |
| ------------- | -------------- | -------------------------------- | ----- |
| **`records`** | `NdefRecord[]` | The records of the NDEF message. | 0.0.1 |

#### NdefRecord

| Prop          | Type             | Description                                                                                                              | Since |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`id`**      | `number[]`       | The record identifier as byte array.                                                                                     | 0.0.1 |
| **`payload`** | `number[]`       | The payload field data as byte array.                                                                                    | 0.0.1 |
| **`tnf`**     | `TypeNameFormat` | The record type name format which indicates the structure of the value of the `type` field.                              | 0.0.1 |
| **`type`**    | `number[]`       | The type of the record payload. This should be used in conjunction with the `tnf` field to determine the payload format. | 0.0.1 |

#### RespondOptions

| Prop       | Type       | Description    | Since |
| ---------- | ---------- | -------------- | ----- |
| **`data`** | `number[]` | Bytes to send. | 6.3.0 |

#### TransceiveResult

| Prop           | Type       | Description                 | Since |
| -------------- | ---------- | --------------------------- | ----- |
| **`response`** | `number[]` | Bytes received in response. | 0.3.0 |

#### TransceiveOptions

| Prop                       | Type                    | Description                                                                                                                                                                                                       | Since |
| -------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`techType`**             | `NfcTagTechType`        | The NFC tag technology to connect with. Only available on iOS.                                                                                                                                                    | 0.3.0 |
| **`data`**                 | `number[]`              | Bytes to send.                                                                                                                                                                                                    | 0.3.0 |
| **`iso15693RequestFlags`** | `Iso15693RequestFlag[]` | The request flags for the NFC tag technology type `NfcV` (ISO 15693-3). Only available on iOS 14+                                                                                                                 | 0.3.0 |
| **`iso15693CommandCode`**  | `number`                | The custom command code defined by the IC manufacturer for the NFC tag technology type `NfcV` (ISO 15693-3). Valid range is 0xA0 to 0xDF inclusively, 0x23 and 0x24 are also supported. Only available on iOS 14+ | 0.3.0 |

#### ConnectOptions

| Prop           | Type             | Description                                                        | Since |
| -------------- | ---------------- | ------------------------------------------------------------------ | ----- |
| **`techType`** | `NfcTagTechType` | The NFC tag technology to connect with. Only available on Android. | 6.0.0 |

#### IsAvailableResult

| Prop      | Type      | Description                                                          | Since |
| --------- | --------- | -------------------------------------------------------------------- | ----- |
| **`hce`** | `boolean` | Whether or not Host Card Emulation (HCE) is available on the device. | 7.2.0 |
| **`nfc`** | `boolean` | Whether or not NFC is available on the device.                       | 7.2.0 |

#### IsSupportedResult

| Prop              | Type      | Description                                                          | Since |
| ----------------- | --------- | -------------------------------------------------------------------- | ----- |
| **`isSupported`** | `boolean` |                                                                      | 0.0.1 |
| **`nfc`**         | `boolean` | Whether or not NFC is supported on the device.                       | 6.3.0 |
| **`hce`**         | `boolean` | Whether or not Host Card Emulation (HCE) is supported on the device. | 6.3.0 |

#### IsEnabledResult

| Prop            | Type      | Since |
| --------------- | --------- | ----- |
| **`isEnabled`** | `boolean` | 0.0.1 |

#### GetAntennaInfoResult

| Prop                    | Type        | Description                               | Since |
| ----------------------- | ----------- | ----------------------------------------- | ----- |
| **`availableAntennas`** | `Antenna[]` | The available NFC antennas on the device. | 6.1.0 |
| **`deviceHeight`**      | `number`    | The height of the device in millimeters.  | 6.1.0 |
| **`deviceWidth`**       | `number`    | The width of the device in millimeters.   | 6.1.0 |
| **`isDeviceFoldable`**  | `boolean`   | Whether or not the device is foldable.    | 6.1.0 |

#### Antenna

| Prop            | Type     | Description                                                   | Since |
| --------------- | -------- | ------------------------------------------------------------- | ----- |
| **`locationX`** | `number` | The location of the NFC antenna on the X axis in millimeters. | 6.1.0 |
| **`locationY`** | `number` | The location of the NFC antenna on the Y axis in millimeters. | 6.1.0 |

#### SetAlertMessageOptions

| Prop          | Type     | Description                                                             | Since |
| ------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`message`** | `string` | The custom message, which is displayed in the NFC Reader Session alert. | 6.2.0 |

#### PermissionResult

| Prop      | Type              | Description                                        | Since |
| --------- | ----------------- | -------------------------------------------------- | ----- |
| **`nfc`** | `PermissionState` | Permission state for reading and writing NFC tags. | 0.0.1 |

#### PluginListenerHandle

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

#### CommandReceivedEvent

| Prop       | Type       | Description                                  | Since |
| ---------- | ---------- | -------------------------------------------- | ----- |
| **`data`** | `number[]` | The command received from the remote device. | 6.3.0 |

#### NfcLinkDeactivatedEvent

| Prop         | Type                 | Description                               | Since |
| ------------ | -------------------- | ----------------------------------------- | ----- |
| **`reason`** | `DeactivationReason` | The reason why the deactivation occurred. | 6.3.0 |

#### NfcTagScannedEvent

| Prop         | Type     | Description          | Since |
| ------------ | -------- | -------------------- | ----- |
| **`nfcTag`** | `NfcTag` | The scanned NFC tag. | 0.0.1 |

#### NfcTag

| Prop                   | Type               | Description                                                                                        | Since |
| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | ----- |
| **`atqa`**             | `number[]`         | The ATQA/SENS_RES bytes of an NFC A tag. Only available on Android.                                | 0.0.1 |
| **`applicationData`**  | `number[]`         | The Application Data bytes from ATQB/SENSB_RES of an NFC B tag. Only available on Android and iOS. | 0.0.1 |
| **`barcode`**          | `number[]`         | The barcode bytes of an NfcBarcode tag. Only available on Android.                                 | 0.0.1 |
| **`canMakeReadOnly`**  | `boolean`          | Whether the NDEF tag can be made read-only or not. Only available on Android.                      | 0.0.1 |
| **`dsfId`**            | `number[]`         | The DSF ID bytes of an NFC V tag. Only available on Android.                                       | 0.0.1 |
| **`hiLayerResponse`**  | `number[]`         | The higher layer response bytes of an ISO-DEP tag. Only available on Android.                      | 0.0.1 |
| **`historicalBytes`**  | `number[]`         | The historical bytes of an ISO-DEP tag. Only available on Android and iOS.                         | 0.0.1 |
| **`id`**               | `number[]`         | The tag identifier (low level serial number) which is used for anti-collision and identification.  | 0.0.1 |
| **`isWritable`**       | `boolean`          | Whether the NDEF tag is writable or not. Only available on Android and iOS.                        | 0.0.1 |
| **`manufacturer`**     | `number[]`         | The manufacturer bytes of an NFC F tag. Only available on Android and iOS.                         | 0.0.1 |
| **`manufacturerCode`** | `number`           | The Integrated Circuit (IC) manufacturer code of an NFC V tag. Only available on iOS.              | 6.3.0 |
| **`maxSize`**          | `number`           | The maximum NDEF message size in bytes. Only available on Android and iOS.                         | 0.0.1 |
| **`message`**          | `NdefMessage`      | The NDEF-formatted message.                                                                        | 0.0.1 |
| **`protocolInfo`**     | `number[]`         | The Protocol Info bytes from ATQB/SENSB_RES of an NFC B tag. Only available on Android.            | 0.0.1 |
| **`responseFlags`**    | `number[]`         | The Response Flag bytes of an NFC V tag. Only available on Android.                                | 0.0.1 |
| **`sak`**              | `number[]`         | The SAK/SEL_RES bytes of an NFC A tag. Only available on Android.                                  | 0.0.1 |
| **`systemCode`**       | `number[]`         | The System Code bytes of an NFC F tag. Only available on Android and iOS.                          | 0.0.1 |
| **`techTypes`**        | `NfcTagTechType[]` | The technologies available in this tag. Only available on Android and iOS.                         | 0.0.1 |
| **`type`**             | `NfcTagType`       | The NDEF tag type. Only available on Android and iOS.                                              | 0.0.1 |

#### ScanSessionErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### NfcTagTechType

| Members                | Value                 | Description                                                                   | Since |
| ---------------------- | --------------------- | ----------------------------------------------------------------------------- | ----- |
| **`NfcA`**             | `'NFC_A'`             | The NFC-A (ISO 14443-3A) tag technology. Only available on Android.           | 0.0.1 |
| **`NfcB`**             | `'NFC_B'`             | The NFC-B (ISO 14443-3B) tag technology. Only available on Android.           | 0.0.1 |
| **`NfcF`**             | `'NFC_F'`             | The NFC-F (JIS 6319-4) tag technology. Only available on Android and iOS.     | 0.0.1 |
| **`NfcV`**             | `'NFC_V'`             | The NFC-V (ISO 15693) tag technology. Only available on Android and iOS.      | 0.0.1 |
| **`IsoDep`**           | `'ISO_DEP'`           | The ISO-DEP (ISO 14443-4) tag technology. Only available on Android.          | 0.0.1 |
| **`Iso7816`**          | `'ISO_7816'`          | The ISO 7816 tag technology. Only available on iOS.                           | 5.1.0 |
| **`Ndef`**             | `'NDEF'`              | The NDEF tag technology. Only available on Android.                           | 0.0.1 |
| **`MifareClassic`**    | `'MIFARE_CLASSIC'`    | The MIFARE Classic tag technology. Only available on Android.                 | 0.0.1 |
| **`MifareDesfire`**    | `'MIFARE_DESFIRE'`    | The MIFARE Desfire tag technology. Only available on iOS.                     | 5.1.0 |
| **`MifarePlus`**       | `'MIFARE_PLUS'`       | The MIFARE Plus tag technology. Only available on iOS.                        | 5.1.0 |
| **`MifareUltralight`** | `'MIFARE_ULTRALIGHT'` | The MIFARE Ultralight tag technology. Only available on Android and iOS.      | 0.0.1 |
| **`NfcBarcode`**       | `'NFC_BARCODE'`       | The technology of a tag containing just a barcode. Only available on Android. | 0.0.1 |
| **`NdefFormatable`**   | `'NDEF_FORMATABLE'`   | The NDEF formatable tag technology. Only available on Android.                | 0.0.1 |

#### PollingOption

| Members        | Value        | Description                                                   | Since |
| -------------- | ------------ | ------------------------------------------------------------- | ----- |
| **`iso14443`** | `'iso14443'` | The option for detecting ISO 7816-compatible and MIFARE tags. | 0.2.0 |
| **`iso15693`** | `'iso15693'` | The option for detecting ISO 15693 tags.                      | 0.2.0 |
| **`iso18092`** | `'iso18092'` | The option for detecting FeliCa tags.                         | 0.2.0 |

#### TypeNameFormat

| Members           | Value | Description                                                                                            | Since |
| ----------------- | ----- | ------------------------------------------------------------------------------------------------------ | ----- |
| **`Empty`**       | `0`   | An empty record with no type or payload.                                                               | 0.0.1 |
| **`WellKnown`**   | `1`   | A predefined type defined in the RTD specification of the NFC Forum.                                   | 0.0.1 |
| **`MimeMedia`**   | `2`   | An Internet media type as defined in RFC 2046.                                                         | 0.0.1 |
| **`AbsoluteUri`** | `3`   | A URI as defined in RFC 3986.                                                                          | 0.0.1 |
| **`External`**    | `4`   | A user-defined value that is based on the rules of the NFC Forum Record Type Definition specification. | 0.0.1 |
| **`Unknown`**     | `5`   | Type is unknown.                                                                                       | 0.0.1 |
| **`Unchanged`**   | `6`   | Indicates the payload is an intermediate or final chunk of a chunked NDEF Record.                      | 0.0.1 |

#### Iso15693RequestFlag

| Members                   | Value                   | Since |
| ------------------------- | ----------------------- | ----- |
| **`address`**             | `'address'`             | 0.3.0 |
| **`commandSpecificBit8`** | `'commandSpecificBit8'` | 0.3.0 |
| **`dualSubCarriers`**     | `'dualSubCarriers'`     | 0.3.0 |
| **`highDataRate`**        | `'highDataRate'`        | 0.3.0 |
| **`option`**              | `'option'`              | 0.3.0 |
| **`protocolExtension`**   | `'protocolExtension'`   | 0.3.0 |
| **`select`**              | `'select'`              | 0.3.0 |

#### DeactivationReason

| Members          | Value | Description                                                       | Since |
| ---------------- | ----- | ----------------------------------------------------------------- | ----- |
| **`LinkLoss`**   | `0`   | Indicates deactivation was due to the NFC link being lost.        | 6.3.0 |
| **`Deselected`** | `1`   | Indicates deactivation was due to a different AID being selected. | 6.3.0 |

#### NfcTagType

| Members                 | Value                   | Description                        | Since |
| ----------------------- | ----------------------- | ---------------------------------- | ----- |
| **`NfcForumType1`**     | `'NFC_FORUM_TYPE_1'`    | Only available on Android.         | 0.0.1 |
| **`NfcForumType2`**     | `'NFC_FORUM_TYPE_2'`    | Only available on Android.         | 0.0.1 |
| **`NfcForumType3`**     | `'NFC_FORUM_TYPE_3'`    | Only available on Android and iOS. | 0.0.1 |
| **`NfcForumType4`**     | `'NFC_FORUM_TYPE_4'`    | Only available on Android.         | 0.0.1 |
| **`MifareClassic`**     | `'MIFARE_CLASSIC'`      | Only available on Android.         | 0.0.1 |
| **`MifareDesfire`**     | `'MIFARE_DESFIRE'`      |                                    | 0.0.1 |
| **`MifarePlus`**        | `'MIFARE_PLUS'`         | Only available on Android.         | 0.0.1 |
| **`MifarePro`**         | `'MIFARE_PRO'`          | Only available on Android.         | 0.0.1 |
| **`MifareUltralight`**  | `'MIFARE_ULTRALIGHT'`   | Only available on Android.         | 0.0.1 |
| **`MifareUltralightC`** | `'MIFARE_ULTRALIGHT_C'` | Only available on Android.         | 0.0.1 |

## Utils

This plugin provides a utility class `NfcUtils` that can be used for various NFC-related operations, for example, creating NDEF records:

```
import { NfcUtils } from '@capawesome-team/capacitor-nfc';

const createNdefTextRecord = () => {
  const utils = new NfcUtils();
  const { record } = utils.createNdefTextRecord({ text: 'Capacitor NFC Plugin' });
  return record;
};
```

See [docs/utils/README.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/docs/utils/README.md) for more information.

## Troubleshooting

##### `The connection to service named com.apple.nfcd.service.corenfc was invalidated from this process`

This error occurs on iOS when the required NFC capability is not added to the app. To fix this, add the `Near Field Communication Tag Reading` capability in Xcode under the `Signing & Capabilities` tab. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

## FAQ

### What do I need to configure before using the plugin on iOS?

You need to enable the `Near Field Communication Tag Reading` capability in Xcode, make sure the `App.entitlements` file contains the `com.apple.developer.nfc.readersession.formats` key, and add the `NFCReaderUsageDescription` key to the `Info.plist` file to tell the user why the app needs to use NFC. See the [Installation](#installation) section for details. If the capability is missing, the scan session fails with an error, as described in the [Troubleshooting](#troubleshooting) section.

### Is Host Card Emulation (HCE) available on all platforms?

No, card emulation is only available on Android. The `respond(...)` method and the `commandReceived` event are Android-only, and you need to declare an HCE service in your `AndroidManifest.xml` as described in the [Installation](#installation) section. You can check whether HCE is supported on the device using the `isSupported()` method.

### Can I launch my app by scanning an NFC tag?

Yes. On Android, you need to add an intent filter to your `AndroidManifest.xml` as described in the [Android documentation](https://developer.android.com/guide/topics/connectivity/nfc/nfc#dispatching). On iOS, the tag requires a URI record containing either a universal link or a supported URL scheme, as described in the [Core NFC documentation](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032598). See the [Installation](#installation) section for details.

### What is the difference between `isSupported` and `isEnabled`?

The `isSupported()` method returns whether the device supports NFC and Host Card Emulation (HCE) at all, while the `isEnabled()` method returns whether NFC is currently enabled. On Android, you can open the NFC device settings with `openSettings()` so that the user can enable NFC. On iOS and Web, `isEnabled()` reflects whether NFC reading is available on the device, since iOS does not expose a global NFC on/off setting.

### Can making an NFC tag read-only be undone?

No, the `makeReadOnly()` method permanently write-protects the tag and cannot be undone. On Android, you can check the `canMakeReadOnly` property of the scanned tag to find out whether it can be made read-only at all.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with Bluetooth Low Energy (BLE) devices in the central and peripheral role.
- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information such as connection status and type, and listen for network changes.
- [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/LICENSE).

# Capacitor Node.js Plugin

Capacitor plugin for running [Node.js](https://nodejs.org/) in mobile apps.[1](#fn:1)[2](#fn:2)

## Features

The Capacitor Node.js plugin is one of the most complete solutions for running Node.js in Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🚀 **Node.js runtime**: Embeds a complete Node.js runtime based on [Node.js for Mobile Apps](https://github.com/nodejs-mobile/nodejs-mobile).
- 🧵 **Background thread**: Runs the Node.js engine on a dedicated background thread to avoid blocking the UI.
- 🔁 **Bidirectional communication**: Event-based message passing between the Capacitor app and the Node.js runtime.
- 📦 **npm ecosystem**: Use npm packages that are not browser-compatible and rely on Node.js core modules.
- 🛠️ **Configurable**: Start the Node.js runtime automatically or manually with custom arguments, environment variables and script.
- 🤝 **Compatibility**: Works alongside the [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/), [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/) and [Zip](https://capawesome.io/docs/sdks/capacitor/zip/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Node.js plugin is typically used whenever an app needs functionality that only the Node.js ecosystem provides, for example:

- **Node.js-only libraries**: Use npm packages that are not browser-compatible because they rely on Node.js core modules.
- **Code reuse**: Reuse existing Node.js code in your mobile app instead of rewriting it for the browser.
- **Background processing**: Offload heavy work to the Node.js engine, which runs on a dedicated background thread and does not block the UI.
- **Local data processing**: Process and persist data on the device using the writable directory provided by the Node.js runtime.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.0.x          | >=8.x.x           | Active support |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/nodejs/example).

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-nodejs` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-nodejs
npx cap sync
```

**Attention**: This plugin embeds the [Node.js for Mobile Apps](https://github.com/nodejs-mobile/nodejs-mobile) runtime binaries. The binaries are not included in the npm package but downloaded on demand: the Android binaries are downloaded by the Gradle build and the iOS binaries are downloaded during `npm install` (only on macOS). Set the `CAPACITOR_NODEJS_SKIP_DOWNLOAD` environment variable to `1` to skip the iOS download.

### Android

#### Variables

If needed, you can define the following project variables in your app's `variables.gradle` file to change the default version of the runtime:

- `$nodejsMobileVersion` version of the Node.js for Mobile Apps runtime (default: `18.20.4-capawesome.1`, a [16 KB page size compatible build](https://github.com/capawesome-team/nodejs-mobile/releases))
- `$nodejsMobileAndroidUrl` download URL of the Android runtime binaries (default: GitHub release of `$nodejsMobileVersion`)
- `$nodejsMobileAndroidSha256` SHA-256 checksum of the Android runtime binaries download (default: checksum of `$nodejsMobileVersion`)

### iOS

This plugin currently only supports **Swift Package Manager**. CocoaPods is not supported.

If you install dependencies with disabled lifecycle scripts (e.g. `npm install --ignore-scripts`), the iOS runtime binaries are not downloaded automatically. In this case, run the download script manually before building your app:

```
node node_modules/@capawesome/capacitor-nodejs/scripts/postinstall.js
```

## Configuration

| Prop            | Type       | Description                                                                                                  | Default                                                                                                                                                                                                                                                        | Since    |
| --------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **`nodeDir`**   | `string`   | The directory of the Node.js project, relative to the Capacitor `webDir`. Only available on Android and iOS. | `'nodejs'`                                                                                                                                                                                                                                                     | 0.0.1    |
| **`startMode`** | \`'manual' | 'auto'\`                                                                                                     | The start mode of the Node.js runtime. If set to `auto`, the Node.js runtime starts automatically when the app is launched. If set to `manual`, the Node.js runtime must be started manually using the `start(...)` method. Only available on Android and iOS. | `'auto'` |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "Nodejs": {
      "nodeDir": 'custom-nodejs',
      "startMode": 'manual'
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-nodejs" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Nodejs: {
      nodeDir: 'custom-nodejs',
      startMode: 'manual',
    },
  },
};

export default config;
```

## Usage

The following examples show how to set up the Node.js project, communicate between Node.js and the Capacitor app, start the runtime manually, wait for it to be ready, and exchange messages with it.

### Set up the Node.js project

The plugin runs the Node.js project located in the `nodejs` directory (see the `nodeDir` configuration option) inside your Capacitor `webDir`. Make sure your web build outputs the Node.js project to this directory, for example by placing it in the `public` directory of your web project:

```
my-app
├── capacitor.config.json   // webDir: 'dist'
└── src
    └── public
        └── nodejs
            ├── package.json
            └── index.js
```

The `package.json` file of the Node.js project defines the script file to run in the `main` field:

```
{
  "name": "nodejs-project",
  "version": "1.0.0",
  "main": "index.js"
}
```

### Communicate with the Capacitor app from Node.js

Inside the script file (`index.js` in this example), the built-in `bridge` module provides the communication channel to the Capacitor app:

```
const { app, channel } = require('bridge');

// Receive messages from the Capacitor app.
channel.on('my-event', (...args) => {
  // Send messages to the Capacitor app.
  channel.post('my-response', 'Hello from Node.js!');
});

// Get a writable directory for persistent file storage.
const dataDir = app.datadir();

// Listen for app lifecycle events.
app.on('pause', pauseLock => {
  pauseLock.release();
});
app.on('resume', () => {});
```

**Attention**: The Node.js project directory may be overwritten during app updates. Store persistent data in the directory returned by `app.datadir()`.

### Start the Node.js runtime manually

By default, the Node.js runtime starts automatically when the app is launched. If the `startMode` configuration option is set to `manual`, start it yourself with custom arguments, environment variables and script:

```
import { Nodejs } from '@capawesome/capacitor-nodejs';

const start = async () => {
  // Only available if the `startMode` configuration option is set to `manual`.
  await Nodejs.start({
    args: ['--option', 'value'],
    env: { MY_ENV_VAR: 'value' },
    script: 'custom-main.js',
  });
};
```

### Wait for the Node.js runtime to be ready

The Node.js runtime is considered ready as soon as the Node.js project has required the `bridge` module. Check the current state with `isReady()` or listen for the `ready` event:

```
import { Nodejs } from '@capawesome/capacitor-nodejs';

const isReady = async () => {
  const { ready } = await Nodejs.isReady();
  return ready;
};

const addReadyListener = async () => {
  await Nodejs.addListener('ready', () => {
    console.log('The Node.js runtime is ready.');
  });
};
```

### Exchange messages with the Node.js runtime

Once the Node.js runtime is ready, send messages to it and listen for messages received from it:

```
import { Nodejs } from '@capawesome/capacitor-nodejs';

const send = async () => {
  await Nodejs.send({
    eventName: 'my-event',
    args: ['Hello from Capacitor!'],
  });
};

const addMessageListener = async () => {
  await Nodejs.addListener('message', event => {
    console.log('Received message:', event.eventName, event.args);
  });
};
```

### Use npm packages

To use npm packages, run `npm install --omit=dev` inside the Node.js project directory before building your web project. It's recommended to bundle the Node.js project into a single file (e.g. with [esbuild](https://esbuild.github.io/)) to improve the startup time.

## API

- [`isReady()`](#isready)
- [`send(...)`](#send)
- [`start(...)`](#start)
- [`addListener('message', ...)`](#addlistenermessage-)
- [`addListener('ready', ...)`](#addlistenerready-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### isReady()

```
isReady() => Promise<IsReadyResult>
```

Check if the Node.js runtime is ready to receive messages.

The Node.js runtime is considered ready as soon as the Node.js project has required the `bridge` module.

Only available on Android and iOS.

**Returns:** `Promise<IsReadyResult>`

**Since:** 0.0.1

______________________________________________________________________

### send(...)

```
send(options: SendOptions) => Promise<void>
```

Send a message to the Node.js runtime.

This method is only available when the Node.js runtime is ready. Use the `isReady()` method or the `ready` event to check if the Node.js runtime is ready.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `SendOptions` |

**Since:** 0.0.1

______________________________________________________________________

### start(...)

```
start(options?: StartOptions | undefined) => Promise<void>
```

Start the Node.js runtime manually.

This method is only available if the `startMode` configuration option is set to `manual`.

**Attention**: The Node.js runtime can only be started once per app launch. Stopping and restarting the Node.js runtime is not supported.

Only available on Android and iOS.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `StartOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('message', ...)

```
addListener(eventName: 'message', listenerFunc: (event: MessageEvent) => void) => Promise<PluginListenerHandle>
```

Called when a message is received from the Node.js runtime.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'message'`                     |
| **`listenerFunc`** | `(event: MessageEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('ready', ...)

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

Called when the Node.js runtime is ready to receive messages.

Only available on Android and iOS.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'ready'`    |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### IsReadyResult

| Prop        | Type      | Description                                                      | Since |
| ----------- | --------- | ---------------------------------------------------------------- | ----- |
| **`ready`** | `boolean` | Whether or not the Node.js runtime is ready to receive messages. | 0.0.1 |

#### SendOptions

| Prop            | Type           | Description                                           | Since |
| --------------- | -------------- | ----------------------------------------------------- | ----- |
| **`args`**      | `MessageArg[]` | The arguments to send to the Node.js runtime.         | 0.0.1 |
| **`eventName`** | `string`       | The name of the event to send to the Node.js runtime. | 0.0.1 |

#### StartOptions

| Prop         | Type                         | Description                                                                    | Default                                                           | Since |
| ------------ | ---------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ----- |
| **`args`**   | `string[]`                   | The arguments to pass to the Node.js process.                                  |                                                                   | 0.0.1 |
| **`env`**    | `{ [key: string]: string; }` | The environment variables to set for the Node.js process.                      |                                                                   | 0.0.1 |
| **`script`** | `string`                     | The path of the script file to run, relative to the Node.js project directory. | `The main field of the package.json file of the Node.js project.` | 0.0.1 |

#### PluginListenerHandle

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

#### MessageEvent

| Prop            | Type           | Description                                              | Since |
| --------------- | -------------- | -------------------------------------------------------- | ----- |
| **`args`**      | `MessageArg[]` | The arguments received from the Node.js runtime.         | 0.0.1 |
| **`eventName`** | `string`       | The name of the event received from the Node.js runtime. | 0.0.1 |

### Type Aliases

#### MessageArg

A single argument of a message that is exchanged with the Node.js runtime.

The value must be JSON-serializable.

`string | number | boolean | null | MessageArg[] | { [key: string]: MessageArg }`

## Limitations

The underlying [Node.js for Mobile Apps](https://github.com/nodejs-mobile/nodejs-mobile) runtime has some limitations that you should be aware of:

- **Single instance**: The Node.js runtime can only be started once per app launch. Stopping and restarting the runtime is not supported.
- **No child processes**: The `child_process` module is not supported on mobile platforms.
- **No JIT on iOS**: On iOS, the JavaScript engine runs in interpreter-only mode (no JIT compilation), which results in slower JavaScript execution compared to Android.
- **App size**: Embedding the Node.js runtime increases the app size by several tens of megabytes per CPU architecture.
- **Native addons**: Node.js native addons are only supported on Android if they are provided as prebuilds (see [`node-gyp-build`](https://github.com/prebuild/node-gyp-build)) for the target architectures.
- **`process.exit()`**: Calling `process.exit()` is not allowed by the Apple App Store guidelines.

## FAQ

### Which Node.js version is supported?

The plugin currently runs Node.js `18.20.4`, the latest version available from [Node.js for Mobile Apps](https://github.com/nodejs-mobile/nodejs-mobile). Support for newer Node.js versions requires self-built runtime binaries for mobile platforms, which we are evaluating.

### Why is there no `stop()` method?

The underlying runtime only supports a single Node.js instance per app launch and provides no API to stop or restart it. A `stop()` method would therefore leave the app in a state where Node.js could never be started again until the app is restarted. If you need to stop work in the Node.js runtime, send a message (e.g. a `shutdown` event) and let your Node.js code stop its servers and timers. The idle runtime consumes negligible resources.

### Where should I store persistent data in the Node.js project?

Store persistent data in the directory returned by `app.datadir()` of the built-in `bridge` module. The Node.js project directory itself may be overwritten during app updates, so any files written there can be lost.

### Why is JavaScript execution slower on iOS than on Android?

On iOS, the JavaScript engine runs in interpreter-only mode without JIT compilation, which results in slower JavaScript execution compared to Android. This is a limitation of the underlying Node.js for Mobile Apps runtime. See the [Limitations](#limitations) section for more details.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/): Run background tasks in your Capacitor app.
- [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/): Access SQLite databases with support for encryption, transactions, and schema migrations.
- [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Zip and unzip files and directories.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nodejs/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nodejs/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by the OpenJS Foundation or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `Node.js` is a registered trademark of the OpenJS Foundation. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor OAuth Plugin

Capacitor plugin for communicating with OAuth 2.0 and OpenID Connect providers.[1](#fn:1)[2](#fn:2)

## Features

The Capacitor OAuth plugin is one of the most complete authentication solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🌐 **Providers**: Works with any OAuth 2.0 / OpenID Connect provider, including Auth0, Azure AD, Amazon Cognito, Okta and OneLogin.
- 🔐 **PKCE**: Implements the Authorization Code flow with Proof Key for Code Exchange (PKCE).
- 🔍 **Auto-discovery**: Automatically fetches endpoints via OpenID Connect discovery.
- 🔄 **Token Refresh**: Refresh access tokens using a refresh token.
- 🪪 **JWT Decoding**: Decode JWT ID tokens without verification.
- 🪶 **Lightweight**: Just a single dependency and zero unnecessary bloat.
- 🤝 **Compatibility**: Compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin to securely store tokens.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The OAuth plugin is typically used whenever an app needs to authenticate users against an OAuth 2.0 or OpenID Connect provider, for example:

- **Enterprise sign-in**: Authenticate users against identity providers such as Auth0, Azure AD, Amazon Cognito, Okta or OneLogin using the Authorization Code flow with PKCE.
- **Social login**: Sign in users with providers like Google that support OpenID Connect discovery.
- **Session management**: Keep users signed in by refreshing access tokens with a refresh token and checking token expiration.
- **User profiles**: Decode the JWT ID token to access the user's claims.
- **Auth Connect migration**: Replace the discontinued Ionic Auth Connect plugin with an actively maintained alternative.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [capawesome-team/capacitor-oauth-demo](https://github.com/capawesome-team/capacitor-oauth-demo)

| Android | iOS | Web |
| ------- | --- | --- |
|         |     |     |

## Guides

- [Announcing the Capacitor OAuth Plugin](https://capawesome.io/blog/announcing-the-capacitor-oauth-plugin/)
- [How to Use Better Auth in Capacitor Apps](https://capawesome.io/blog/how-to-use-better-auth-in-capacitor-apps/)
- [How to Sign in with Okta using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-okta-using-capacitor/)
- [How to Sign in with Auth0 using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-auth0-using-capacitor/)
- [How to Sign in with Azure Entra ID using Capacitor](https://capawesome.io/blog/how-to-sign-in-with-azure-entra-id-using-capacitor/)
- [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/)
- [Alternative to the Ionic Auth Connect Plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-oauth` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-oauth
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$appAuthVersion` version of `net.openid:appauth` (default: `0.11.1`)

#### Redirect Scheme

Add the following to your app's `build.gradle` file to configure the redirect scheme used by AppAuth:

```
android {
    defaultConfig {
        manifestPlaceholders = [appAuthRedirectScheme: "com.example.app"]
    }
}
```

Replace `com.example.app` with the scheme of your redirect URI.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

## Usage

The following examples show how to sign in a user, handle the redirect callback on the Web, refresh the access token, sign out a user, and decode an ID token, using the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin to securely store the tokens.

### Sign in a user

Start an OAuth 2.0 authorization code flow with PKCE using the `login(...)` method. When you provide the `issuerUrl`, the plugin automatically fetches the authorization and token endpoints via OpenID Connect discovery:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const login = async () => {
  // Sign in the user
  const result = await Oauth.login({
    issuerUrl: 'https://accounts.google.com',
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'com.example.app://oauth/callback',
    scopes: ['openid', 'profile', 'email', 'offline_access'],
  });
  console.log('Access token:', result.accessToken);
  console.log('ID token:', result.idToken);
  console.log('Refresh token:', result.refreshToken);
  // Store the tokens securely
  await SecurePreferences.set({
    key: 'tokens',
    value: JSON.stringify(result),
  });
};
```

### Handle the redirect callback on the Web

On the Web, call the `handleRedirectCallback()` method on page load when the URL contains authorization response parameters. This method is only available on Web:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';
import { Capacitor } from '@capacitor/core';

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== 'web') {
    return;
  }
  // Handle the redirect callback on web
  const result = await Oauth.handleRedirectCallback();
  console.log('Access token:', result.accessToken);
};
```

### Refresh the access token

Use the `refreshToken(...)` method to obtain a new access token using the refresh token from the login:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const refreshToken = async () => {
  const result = await Oauth.refreshToken({
    issuerUrl: 'https://accounts.google.com',
    clientId: 'YOUR_CLIENT_ID',
    refreshToken: 'YOUR_REFRESH_TOKEN',
  });
  console.log('New access token:', result.accessToken);
};
```

### Sign out a user

End the OAuth session by calling the provider's end-session endpoint using the `logout(...)` method:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const logout = async () => {
  await Oauth.logout({
    issuerUrl: 'https://accounts.google.com',
    idToken: 'YOUR_ID_TOKEN',
    postLogoutRedirectUrl: 'com.example.app://oauth/logout',
  });
};
```

### Decode an ID token

Use the `decodeIdToken(...)` method to decode a JWT ID token without verification and access its claims:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const decodeIdToken = async () => {
  const result = await Oauth.decodeIdToken({
    token: 'YOUR_ID_TOKEN',
  });
  console.log('Payload:', result.payload);
};
```

## API

- [`decodeIdToken(...)`](#decodeidtoken)
- [`getAccessTokenExpirationDate(...)`](#getaccesstokenexpirationdate)
- [`isAccessTokenAvailable(...)`](#isaccesstokenavailable)
- [`isAccessTokenExpired(...)`](#isaccesstokenexpired)
- [`isRefreshTokenAvailable(...)`](#isrefreshtokenavailable)
- [`handleRedirectCallback()`](#handleredirectcallback)
- [`login(...)`](#login)
- [`logout(...)`](#logout)
- [`refreshToken(...)`](#refreshtoken)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### decodeIdToken(...)

```
decodeIdToken(options: DecodeIdTokenOptions) => Promise<DecodeIdTokenResult>
```

Decode a JWT ID token without verification.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `DecodeIdTokenOptions` |

**Returns:** `Promise<DecodeIdTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### getAccessTokenExpirationDate(...)

```
getAccessTokenExpirationDate(options: GetAccessTokenExpirationDateOptions) => Promise<GetAccessTokenExpirationDateResult>
```

Get the access token expiration date as an ISO 8601 string.

| Param         | Type                                  |
| ------------- | ------------------------------------- |
| **`options`** | `GetAccessTokenExpirationDateOptions` |

**Returns:** `Promise<GetAccessTokenExpirationDateResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAccessTokenAvailable(...)

```
isAccessTokenAvailable(options: IsAccessTokenAvailableOptions) => Promise<IsAccessTokenAvailableResult>
```

Check if an access token is available (non-null and non-empty).

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `IsAccessTokenAvailableOptions` |

**Returns:** `Promise<IsAccessTokenAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAccessTokenExpired(...)

```
isAccessTokenExpired(options: IsAccessTokenExpiredOptions) => Promise<IsAccessTokenExpiredResult>
```

Check if the access token has expired.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `IsAccessTokenExpiredOptions` |

**Returns:** `Promise<IsAccessTokenExpiredResult>`

**Since:** 0.1.0

______________________________________________________________________

### isRefreshTokenAvailable(...)

```
isRefreshTokenAvailable(options: IsRefreshTokenAvailableOptions) => Promise<IsRefreshTokenAvailableResult>
```

Check if a refresh token is available (non-null and non-empty).

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `IsRefreshTokenAvailableOptions` |

**Returns:** `Promise<IsRefreshTokenAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### handleRedirectCallback()

```
handleRedirectCallback() => Promise<HandleRedirectCallbackResult>
```

Handle the redirect callback after a login or logout redirect on the web.

Call this method on page load when the URL contains authorization response parameters.

Only available on Web.

**Returns:** `Promise<LoginResult>`

**Since:** 0.1.0

______________________________________________________________________

### login(...)

```
login(options: LoginOptions) => Promise<LoginResult>
```

Start an OAuth 2.0 authorization code flow with PKCE.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `LoginOptions` |

**Returns:** `Promise<LoginResult>`

**Since:** 0.1.0

______________________________________________________________________

### logout(...)

```
logout(options: LogoutOptions) => Promise<void>
```

End the OAuth session by calling the end-session endpoint.

Note that some providers (e.g. Microsoft Entra ID) may not redirect back to the app after logout and instead show a "You have signed out" page. In this case, the user has to close the browser manually which results in a `USER_CANCELED` error even though the logout was successful.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `LogoutOptions` |

**Since:** 0.1.0

______________________________________________________________________

### refreshToken(...)

```
refreshToken(options: RefreshTokenOptions) => Promise<RefreshTokenResult>
```

Refresh the access token using a refresh token.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `RefreshTokenOptions` |

**Returns:** `Promise<LoginResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### DecodeIdTokenResult

| Prop          | Type                      | Description                                    | Since |
| ------------- | ------------------------- | ---------------------------------------------- | ----- |
| **`header`**  | `Record<string, unknown>` | The decoded JWT header.                        | 0.1.0 |
| **`payload`** | `Record<string, unknown>` | The decoded JWT payload containing the claims. | 0.1.0 |

#### DecodeIdTokenOptions

| Prop        | Type     | Description                        | Since |
| ----------- | -------- | ---------------------------------- | ----- |
| **`token`** | `string` | The JWT ID token string to decode. | 0.1.0 |

#### GetAccessTokenExpirationDateResult

| Prop       | Type     | Description                                             | Since |
| ---------- | -------- | ------------------------------------------------------- | ----- |
| **`date`** | `string` | The access token expiration date as an ISO 8601 string. | 0.1.0 |

#### GetAccessTokenExpirationDateOptions

| Prop                            | Type     | Description                                             | Since |
| ------------------------------- | -------- | ------------------------------------------------------- | ----- |
| **`accessTokenExpirationDate`** | `number` | The access token expiration date in epoch milliseconds. | 0.1.0 |

#### IsAccessTokenAvailableResult

| Prop              | Type      | Description                                         | Since |
| ----------------- | --------- | --------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether the access token is non-null and non-empty. | 0.1.0 |

#### IsAccessTokenAvailableOptions

| Prop              | Type     | Description                | Since |
| ----------------- | -------- | -------------------------- | ----- |
| **`accessToken`** | `string` | The access token to check. | 0.1.0 |

#### IsAccessTokenExpiredResult

| Prop            | Type      | Description                           | Since |
| --------------- | --------- | ------------------------------------- | ----- |
| **`isExpired`** | `boolean` | Whether the access token has expired. | 0.1.0 |

#### IsAccessTokenExpiredOptions

| Prop                            | Type     | Description                                             | Since |
| ------------------------------- | -------- | ------------------------------------------------------- | ----- |
| **`accessTokenExpirationDate`** | `number` | The access token expiration date in epoch milliseconds. | 0.1.0 |

#### IsRefreshTokenAvailableResult

| Prop              | Type      | Description                                          | Since |
| ----------------- | --------- | ---------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether the refresh token is non-null and non-empty. | 0.1.0 |

#### IsRefreshTokenAvailableOptions

| Prop               | Type     | Description                 | Since |
| ------------------ | -------- | --------------------------- | ----- |
| **`refreshToken`** | `string` | The refresh token to check. | 0.1.0 |

#### LoginResult

| Prop                            | Type                     | Description                                                                                            | Since |
| ------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ | ----- |
| **`accessToken`**               | `string`                 | The access token.                                                                                      | 0.1.0 |
| **`accessTokenExpirationDate`** | `number`                 | The access token expiration date in epoch milliseconds.                                                | 0.1.0 |
| **`additionalParameters`**      | `Record<string, string>` | Additional non-standard parameters returned by the token endpoint. All values are returned as strings. | 0.1.8 |
| **`idToken`**                   | `string`                 | The JWT ID token (OpenID Connect).                                                                     | 0.1.0 |
| **`refreshToken`**              | `string`                 | The refresh token.                                                                                     | 0.1.0 |
| **`scope`**                     | `string`                 | The granted scopes as a space-delimited string.                                                        | 0.1.0 |
| **`tokenType`**                 | `string`                 | The token type.                                                                                        | 0.1.0 |

#### LoginOptions

| Prop                                    | Type                     | Description                                                                                                                                                                                                                                                                                                                                                           | Default | Since |
| --------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`additionalParameters`**              | `Record<string, string>` | Additional parameters to include in the authorization request.                                                                                                                                                                                                                                                                                                        |         | 0.1.0 |
| **`authorizationEndpoint`**             | `string`                 | The authorization endpoint URL. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.                                                                                                                                                                                                                                              |         | 0.1.0 |
| **`clientId`**                          | `string`                 | The OAuth client ID.                                                                                                                                                                                                                                                                                                                                                  |         | 0.1.0 |
| **`issuerUrl`**                         | `string`                 | The OpenID Connect issuer URL for auto-discovery. The plugin will fetch the OpenID Connect discovery document from `{issuerUrl}/.well-known/openid-configuration` to obtain the authorization and token endpoint URLs. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.                                                       |         | 0.1.0 |
| **`loginHint`**                         | `string`                 | A hint to the authorization server about the user's identifier to pre-fill the login form.                                                                                                                                                                                                                                                                            |         | 0.1.0 |
| **`prefersEphemeralWebBrowserSession`** | `boolean`                | Whether the authentication session should use an ephemeral web browser session. If `true`, the session will not share cookies or other browsing data with the user's regular browser session. As a side effect, the system consent dialog (e.g. "...wants to use 'example.com' to Sign In") is not shown. Only available on iOS.                                      | `false` | 0.1.5 |
| **`prompt`**                            | `string`                 | The prompt parameter to control the authorization server UI behavior.                                                                                                                                                                                                                                                                                                 |         | 0.1.0 |
| **`redirectUrl`**                       | `string`                 | The redirect URI to use after authentication. **Attention**: On iOS, the redirect URI returned by the provider must exactly match this value (including any trailing slash), otherwise `login(...)` will never resolve. See the [Troubleshooting](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/oauth#troubleshooting) section for details. |         | 0.1.0 |
| **`scopes`**                            | `string[]`               | The OAuth scopes to request.                                                                                                                                                                                                                                                                                                                                          |         | 0.1.0 |
| **`tokenEndpoint`**                     | `string`                 | The token endpoint URL. Either `issuerUrl` or both `authorizationEndpoint` and `tokenEndpoint` must be provided.                                                                                                                                                                                                                                                      |         | 0.1.0 |
| **`uiLocales`**                         | `string[]`               | The end-user's preferred languages for the authorization server UI, as an ordered list of BCP47 language tags.                                                                                                                                                                                                                                                        |         | 0.1.4 |

#### LogoutOptions

| Prop                                    | Type                     | Description                                                                                                                                                                                                                                                                                                                       | Default | Since |
| --------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`additionalParameters`**              | `Record<string, string>` | Additional parameters to include in the end-session request.                                                                                                                                                                                                                                                                      |         | 0.1.0 |
| **`endSessionEndpoint`**                | `string`                 | The end-session endpoint URL. Either `issuerUrl` or `endSessionEndpoint` must be provided.                                                                                                                                                                                                                                        |         | 0.1.0 |
| **`idToken`**                           | `string`                 | The ID token hint for session identification.                                                                                                                                                                                                                                                                                     |         | 0.1.0 |
| **`issuerUrl`**                         | `string`                 | The OpenID Connect issuer URL used to fetch the discovery document at `{issuerUrl}/.well-known/openid-configuration`. Either `issuerUrl` or `endSessionEndpoint` must be provided.                                                                                                                                                |         | 0.1.0 |
| **`postLogoutRedirectUrl`**             | `string`                 | The redirect URI to use after logout.                                                                                                                                                                                                                                                                                             |         | 0.1.0 |
| **`prefersEphemeralWebBrowserSession`** | `boolean`                | Whether the authentication session should use an ephemeral web browser session. If `true`, the session will not share cookies or other browsing data with the user's regular browser session. As a side effect, the system consent dialog (e.g. "...wants to use 'example.com' to Sign Out") is not shown. Only available on iOS. | `false` | 0.1.5 |

#### RefreshTokenOptions

| Prop                       | Type                     | Description                                                                                                                                                                   | Since |
| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`issuerUrl`**            | `string`                 | The OpenID Connect issuer URL used to fetch the discovery document at `{issuerUrl}/.well-known/openid-configuration`. Either `issuerUrl` or `tokenEndpoint` must be provided. | 0.1.0 |
| **`tokenEndpoint`**        | `string`                 | The token endpoint URL. Either `issuerUrl` or `tokenEndpoint` must be provided.                                                                                               | 0.1.0 |
| **`clientId`**             | `string`                 | The OAuth client ID.                                                                                                                                                          | 0.1.0 |
| **`refreshToken`**         | `string`                 | The refresh token obtained from login.                                                                                                                                        | 0.1.0 |
| **`additionalParameters`** | `Record<string, string>` | Additional parameters to include in the token refresh request.                                                                                                                | 0.1.0 |

### Type Aliases

#### HandleRedirectCallbackResult

`LoginResult`

#### RefreshTokenResult

`LoginResult`

## Troubleshooting

##### `login(...)` never resolves on iOS

On iOS, `login(...)` may hang forever (while working on Android and Web) if the redirect URI returned by your provider does not exactly match the `redirectUrl` you passed. The plugin compares scheme, host and path and silently ignores any mismatch, so the promise never settles. The usual culprit is a **trailing slash** added by the provider or its infrastructure (`com.example.app://callback` vs `com.example.app://callback/`).

Compare the returned redirect URI (e.g. via a network proxy such as [Proxyman](https://proxyman.io/)) byte-for-byte with your `redirectUrl` and make them match exactly.

##### In-app browser closes when the app is reopened on Android

With the Capacitor default `android:launchMode="singleTask"`, Android destroys all activities on top of the main activity, including the in-app browser, when the app is reopened via the launcher icon, for example after switching to a mail app to look up a one-time password. The plugin detects this and automatically re-opens the in-app browser so the user can complete the flow. Since the identity provider's session cookies are preserved, the user can usually continue where they left off.

If you prefer to keep the in-app browser (including any entered form data) alive while the app is in the background, you can optionally apply one of the following workarounds in your app:

**Launcher activity (recommended)**: Add a launcher activity that receives the launcher intent instead of your main activity. This way, reopening the app via the launcher icon no longer targets the `singleTask` main activity, so Android brings the task to the foreground without destroying the in-app browser, while your main activity keeps its `singleTask` behavior. Create the following activity next to your `MainActivity` (adjust the package name):

```
package com.example.app;

import android.content.Intent;
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;

public class LauncherActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (!isTaskRoot()) {
            // The app is already running, so just bring the existing task
            // (including any open in-app browser) to the foreground.
            finish();
            return;
        }
        Intent intent = new Intent(this, MainActivity.class);
        intent.replaceExtras(getIntent());
        startActivity(intent);
        finish();
    }
}
```

Then, in your `AndroidManifest.xml` file, move the `MAIN`/`LAUNCHER` intent filter from your main activity to the new launcher activity:

```
<activity
    android:name=".LauncherActivity"
    android:theme="@style/AppTheme.NoActionBarLaunch"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>
```

Everything else on your main activity stays as it is, including `android:launchMode="singleTask"`, `android:exported="true"` and all other intent filters (e.g. for deep links) — only the `MAIN`/`LAUNCHER` intent filter moves.

**`singleTop` launch mode**: Alternatively, set `android:launchMode="singleTop"` on your main activity in the `AndroidManifest.xml` file. Be aware that this may change how Android delivers intents (e.g. deep links) to your app, so make sure to test this change carefully.

## FAQ

### Is this plugin an alternative to Ionic Auth Connect?

Yes. This plugin was built as an actively maintained alternative to [Ionic Auth Connect](https://ionic.io/products/auth-connect), which has been discontinued and reaches end of life on December 31, 2027. It offers a similar feature set:

- OAuth 2.0 and OpenID Connect support for any provider, including Auth0, Azure AD, Amazon Cognito, Okta and OneLogin
- Authorization Code flow with Proof Key for Code Exchange (PKCE)
- Automatic endpoint discovery via OpenID Connect discovery
- Access token refresh using a refresh token
- Logout via the provider's end-session endpoint

### How do I migrate from Ionic Auth Connect?

For an AI-assisted migration of your code, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool and instruct it to use the `ionic-enterprise-sdk-migration` skill to migrate your project from Ionic Auth Connect to `@capawesome-team/capacitor-oauth`. Alternatively, if you want to perform the migration manually, you can follow the instructions in this blog post: [Alternative to the Ionic Auth Connect plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/).

### Why does `login(...)` never resolve on iOS?

This usually happens when the redirect URI returned by your provider does not exactly match the `redirectUrl` you passed, for example because of a trailing slash added by the provider. The plugin compares scheme, host and path and silently ignores any mismatch. See the [Troubleshooting](#troubleshooting) section for details on how to diagnose and fix this.

### Where should I store the tokens?

Tokens are sensitive data and should not be stored in plain text. The plugin is compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin, which securely stores key/value pairs such as tokens, as shown in the [usage examples](#usage) above.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

### How does OAuth compare to Apple, Google, or Facebook Sign-In?

This plugin talks to any OAuth 2.0 / OpenID Connect provider directly, which is the right fit for a custom identity provider or one without a dedicated Capacitor plugin. If you're specifically integrating Apple, Google, or Facebook, their dedicated [Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/), [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/), and [Facebook Sign-In](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/) plugins use each provider's native SDK and are usually simpler to set up than configuring them through generic OAuth.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition.
- [In-App Browser](https://capawesome.io/docs/sdks/capacitor/in-app-browser/): Open the OAuth authorization page in an embedded browser instead of the system browser.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Next steps

Here are a few resources to help you continue:

- Read [Alternative to the Ionic Auth Connect plugin](https://capawesome.io/blog/alternative-to-ionic-auth-connect-plugin/) if you are migrating from Ionic Auth Connect.
- Store tokens and other sensitive data with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/).
- Check out [Getting Started with Insiders](https://capawesome.io/docs/insiders/getting-started/) to learn how to install the plugin.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/oauth/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by the OpenID Foundation or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `OpenID` is a registered trademark of the OpenID Foundation. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor Option Picker Plugin

Capacitor plugin that lets the user pick an option from a list using a native picker.

## Features

- 📋 **Native Picker**: Present the platform's native single-choice picker: a wheel picker on iOS and a Material 3 dialog on Android.
- ✅ **Preselection**: Open the picker with the current value already selected.
- 📝 **Title & Buttons**: Customize the title and the texts of the done and cancel buttons.
- 📚 **Long Lists**: Scroll smoothly through long lists of options on both platforms.
- 🎨 **Themed**: Follows the system appearance or a forced light or dark theme, and adopts your app's Material theme on Android.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Option Picker plugin is typically used as a native replacement for HTML `<select>` elements, for example:

- **Form inputs**: Let the user pick a country, language, or category in a form.
- **Settings screens**: Let the user choose a value such as a unit, a theme, or a refresh interval.
- **Filters and sorting**: Let the user pick a sort order or a filter category in a list view.
- **Guided flows**: Ask the user to pick a value before continuing to the next step.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| iOS |
| --- |
|     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-option-picker` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-option-picker
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxMaterialVersion` version of `com.google.android.material:material` (default: `1.12.0`)

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to present a native option picker and read the selected value.

### Present a picker

Present a native picker with a title and a list of options. Use the `value` option to preselect the current value. The result contains the value of the selected option. Only available on Android and iOS:

```
import { OptionPicker } from '@capawesome/capacitor-option-picker';

const presentPicker = async () => {
  const { value } = await OptionPicker.present({
    title: 'Select a country',
    options: [
      { label: 'Germany', value: 'de' },
      { label: 'France', value: 'fr' },
      { label: 'Spain', value: 'es' },
    ],
    value: 'fr',
  });
  console.log('Selected value:', value);
};
```

### Handle cancellation

If the user cancels or dismisses the picker, the returned promise is rejected with the `ErrorCode.Canceled` error code:

```
import { ErrorCode, OptionPicker } from '@capawesome/capacitor-option-picker';

const presentPicker = async () => {
  try {
    const { value } = await OptionPicker.present({
      options: [
        { label: 'Small', value: 's' },
        { label: 'Medium', value: 'm' },
        { label: 'Large', value: 'l' },
      ],
    });
    console.log('Selected value:', value);
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user canceled the picker.');
    }
  }
};
```

## API

- [`present(...)`](#present)
- [Interfaces](#interfaces)

### present(...)

```
present(options: PresentOptions) => Promise<PresentResult>
```

Present a native picker that lets the user select one option from a list.

The returned promise is rejected with the `ErrorCode.Canceled` error code if the user cancels or dismisses the picker.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `PresentOptions` |

**Returns:** `Promise<PresentResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### PresentResult

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`value`** | `string` | The value of the selected option. | 0.1.0 |

#### PresentOptions

| Prop                   | Type             | Description                                                                                                                | Default    | Since                                                          |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| **`cancelButtonText`** | `string`         | The text of the cancel button.                                                                                             | `'Cancel'` | 0.1.0                                                          |
| **`doneButtonText`**   | `string`         | The text of the done button.                                                                                               | `'Ok'`     | 0.1.0                                                          |
| **`options`**          | `PickerOption[]` | The options the user can choose from. Must contain at least one option.                                                    |            | 0.1.0                                                          |
| **`theme`**            | \`'auto'         | 'light'                                                                                                                    | 'dark'\`   | The theme of the picker. `auto` follows the system appearance. |
| **`title`**            | `string`         | The title of the picker.                                                                                                   |            | 0.1.0                                                          |
| **`value`**            | `string`         | The value of the option that is selected when the picker opens. If no option has this value, the first option is selected. |            | 0.1.0                                                          |

#### PickerOption

| Prop        | Type     | Description                                     | Since |
| ----------- | -------- | ----------------------------------------------- | ----- |
| **`label`** | `string` | The text displayed for the option.              | 0.1.0 |
| **`value`** | `string` | The value returned when the option is selected. | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It presents the platform's own single-choice picker on Android and iOS through a fully typed API: a wheel picker with a toolbar on iOS and a Material 3 dialog on Android, the same controls the operating systems use for `<select>` elements. The current value can be preselected, the title and button texts are customizable, and cancellation is reported with a dedicated error code, all using only official platform APIs. Actively maintained against the latest Capacitor version, it lets a single dependency replace non-native dropdown components.

### Which native UI is used on each platform?

On iOS, the plugin presents a `UIPickerView` in a bottom sheet with a toolbar that contains the cancel button, the title, and the done button. On iOS 26 and later, the bottom sheet uses the system's Liquid Glass design. On Android, the plugin presents a Material 3 dialog with a scrollable single-choice list and a done and cancel button. Both follow the system appearance, including dark mode.

### Does the Android dialog use my app's theme?

Yes, if your app uses a Material Components or Material 3 theme, the dialog inherits its colors and shapes. If your app uses an AppCompat theme (the Capacitor default), the dialog uses a Material 3 theme with the system's dynamic colors on Android 12 and later, and the Material 3 baseline colors on older versions. To use your own brand colors in that case, switch your app theme to a Material 3 theme such as `Theme.Material3.DayNight.NoActionBar`.

### Can I force a light or dark theme?

Yes, set the `theme` option to `light` or `dark`. By default (`auto`), the picker follows the system appearance.

### What happens when the user cancels the picker?

The returned promise is rejected with the `ErrorCode.Canceled` error code. This happens when the user taps the cancel button, taps outside of the picker, swipes the picker down on iOS 26 and later, or presses the back button on Android. See the [Handle cancellation](#handle-cancellation) example.

### Which option is selected when the picker opens?

The option whose value matches the `value` option is selected. If no `value` is provided or no option matches, the first option is selected.

### When should I use the Option Picker instead of the Action Sheet plugin?

Use the Option Picker when the user has to choose a value, for example in a form or a settings screen. It is designed for long lists and highlights the current value. Use the [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/) plugin when the user has to choose between a few actions to perform.

### Does this plugin work on the Web?

No, the `present(...)` method is only available on Android and iOS. On the Web, use a regular HTML `<select>` element instead.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/): Show native action sheets.
- [Datetime Picker](https://capawesome.io/docs/sdks/capacitor/datetime-picker/): Let the user pick a date and time with a native picker.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Display native alert, confirm, and prompt dialogs.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/option-picker/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/option-picker/LICENSE).

# Capacitor Passkeys Plugin

Capacitor plugin to create and authenticate with [passkeys](https://fidoalliance.org/passkeys/) based on the [WebAuthn](https://www.w3.org/TR/webauthn-2/) standard.

## Features

The Capacitor Passkeys plugin is one of the most complete passkey authentication solutions for Capacitor apps. Here are some of the key features:

- 🔐 **Passkey creation**: Register new passkeys with the platform authenticator.
- 🔑 **Passkey authentication**: Authenticate users with their existing passkeys.
- 🌐 **WebAuthn standard**: Uses the WebAuthn JSON serialization so any WebAuthn server library works unchanged.
- 📱 **Availability check**: Check if passkeys are available on the device.
- 🖥️ **Web support**: Full web support via the native WebAuthn browser API.
- 🤝 **Compatibility**: Works alongside the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) and [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Passkeys plugin is typically used to modernize the authentication of an app, for example:

- **Passwordless sign-in**: Let users authenticate with a passkey instead of typing a password.
- **Passkey enrollment**: Let existing users register a passkey for their account after they signed in with their current credentials.
- **Progressive enhancement**: Check with `isAvailable()` whether passkeys are supported on the device and offer them as an alternative to your existing login.
- **Server integration**: Pass the options and results of any WebAuthn server library through unchanged, thanks to the WebAuthn JSON serialization.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-passkeys` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-passkeys
npx cap sync
```

### Android

On Android, passkeys are supported on Android 9 (API level 28) and higher with an available credential provider (e.g. Google Password Manager).

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$androidxCredentialsVersion` version of `androidx.credentials:credentials` and `androidx.credentials:credentials-play-services-auth` (default: `1.5.0`)

#### Digital Asset Links

Your app must be associated with the domain of the relying party (`rp.id` / `rpId`) using [Digital Asset Links](https://developers.google.com/digital-asset-links). For this, host a JSON file at `https://<your-domain>/.well-known/assetlinks.json` that delegates the `common.get_login_creds` permission to your app:

```
[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"
      ]
    }
  }
]
```

Replace `com.example.app` with the application ID of your app and the fingerprint with the SHA-256 fingerprint of your app's signing certificate. Otherwise, the plugin methods will reject with the `DOMAIN_NOT_ASSOCIATED` error code.

### iOS

On iOS, passkeys are supported on iOS 15 and higher.

#### Associated Domains

Your app must be associated with the domain of the relying party (`rp.id` / `rpId`). For this, add the [Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) capability with the `webcredentials` service type to your app:

```
<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:example.com</string>
</array>
```

Additionally, host an [`apple-app-site-association`](https://developer.apple.com/documentation/xcode/supporting-associated-domains) file at `https://<your-domain>/.well-known/apple-app-site-association`:

```
{
  "webcredentials": {
    "apps": ["TEAMID.com.example.app"]
  }
}
```

Replace `TEAMID` with your Apple Developer Team ID and `com.example.app` with the bundle identifier of your app. Otherwise, the plugin methods will reject with the `DOMAIN_NOT_ASSOCIATED` error code.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to create a new passkey, authenticate with an existing passkey, and check whether passkeys are available on the device.

### Create a new passkey

Register a new passkey for a user account. In a real app, the options must be provided by your WebAuthn server, and the result must be passed back to it for verification:

```
import { Passkeys } from '@capawesome/capacitor-passkeys';

const createPasskey = async () => {
  // In a real app, the options must be provided by your WebAuthn server,
  // e.g. via `generateRegistrationOptions()` from SimpleWebAuthn.
  const result = await Passkeys.createPasskey({
    attestation: 'none',
    authenticatorSelection: {
      residentKey: 'required',
      userVerification: 'required',
    },
    challenge: 'dGhpc2lzYWNoYWxsZW5nZQ',
    pubKeyCredParams: [
      { alg: -7, type: 'public-key' },
      { alg: -257, type: 'public-key' },
    ],
    rp: { id: 'example.com', name: 'Example Inc.' },
    user: {
      displayName: 'Jane Doe',
      id: 'anVzdGFyYW5kb21pZA',
      name: 'jane.doe@example.com',
    },
  });
  // Pass the result to your WebAuthn server for verification,
  // e.g. via `verifyRegistrationResponse()` from SimpleWebAuthn.
  return result;
};
```

### Authenticate with an existing passkey

Sign a user in with a passkey that was previously created for your relying party. Again, the options come from your WebAuthn server and the result is verified by it:

```
import { Passkeys } from '@capawesome/capacitor-passkeys';

const getPasskey = async () => {
  // In a real app, the options must be provided by your WebAuthn server,
  // e.g. via `generateAuthenticationOptions()` from SimpleWebAuthn.
  const result = await Passkeys.getPasskey({
    challenge: 'dGhpc2lzYWNoYWxsZW5nZQ',
    rpId: 'example.com',
    userVerification: 'required',
  });
  // Pass the result to your WebAuthn server for verification,
  // e.g. via `verifyAuthenticationResponse()` from SimpleWebAuthn.
  return result;
};
```

### Check if passkeys are available

Check whether passkeys are available on the device before offering them in your login UI. On Android, this returns `true` if the device runs Android 9 (API level 28) or higher. On iOS, this always returns `true`. On Web, this returns `true` if the browser supports WebAuthn and a user-verifying platform authenticator is available:

```
import { Passkeys } from '@capawesome/capacitor-passkeys';

const isAvailable = async () => {
  const { available } = await Passkeys.isAvailable();
  return available;
};
```

## API

- [`createPasskey(...)`](#createpasskey)
- [`getPasskey(...)`](#getpasskey)
- [`isAvailable()`](#isavailable)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### createPasskey(...)

```
createPasskey(options: CreatePasskeyOptions) => Promise<CreatePasskeyResult>
```

Create (register) a new passkey.

The options mirror the WebAuthn `PublicKeyCredentialCreationOptions` JSON serialization so that the values provided by any WebAuthn server library can be passed through unchanged.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `CreatePasskeyOptions` |

**Returns:** `Promise<CreatePasskeyResult>`

**Since:** 0.1.0

______________________________________________________________________

### getPasskey(...)

```
getPasskey(options: GetPasskeyOptions) => Promise<GetPasskeyResult>
```

Get (authenticate with) an existing passkey.

The options mirror the WebAuthn `PublicKeyCredentialRequestOptions` JSON serialization so that the values provided by any WebAuthn server library can be passed through unchanged.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `GetPasskeyOptions` |

**Returns:** `Promise<GetPasskeyResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if passkeys are available on this device.

On **Android**, this returns `true` if the device runs Android 9 (API level 28) or higher. On **iOS**, this always returns `true`. On **Web**, this returns `true` if the browser supports WebAuthn and a user-verifying platform authenticator is available.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CreatePasskeyResult

The result of the passkey creation.

This mirrors the WebAuthn `RegistrationResponseJSON` so it can be passed to any WebAuthn server library for verification.

| Prop                          | Type                             | Description                                                   | Since |
| ----------------------------- | -------------------------------- | ------------------------------------------------------------- | ----- |
| **`authenticatorAttachment`** | `PasskeyAuthenticatorAttachment` | The attachment of the authenticator that created the passkey. | 0.1.0 |
| **`id`**                      | `string`                         | The credential identifier as a base64url-encoded string.      | 0.1.0 |
| **`rawId`**                   | `string`                         | The raw credential identifier as a base64url-encoded string.  | 0.1.0 |
| **`response`**                | `CreatePasskeyResponse`          | The response of the authenticator.                            | 0.1.0 |
| **`type`**                    | `'public-key'`                   | The credential type.                                          | 0.1.0 |

#### CreatePasskeyResponse

The response of the authenticator for the registration of a new passkey.

This mirrors the WebAuthn `AuthenticatorAttestationResponse` JSON serialization.

| Prop                     | Type                 | Description                                                                                  | Since |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------- | ----- |
| **`attestationObject`**  | `string`             | The attestation object as a base64url-encoded string.                                        | 0.1.0 |
| **`authenticatorData`**  | `string`             | The authenticator data as a base64url-encoded string. Only available on Android and Web.     | 0.1.0 |
| **`clientDataJSON`**     | `string`             | The client data as a base64url-encoded string.                                               | 0.1.0 |
| **`publicKey`**          | `string`             | The DER-encoded public key as a base64url-encoded string. Only available on Android and Web. | 0.1.0 |
| **`publicKeyAlgorithm`** | `number`             | The COSE algorithm identifier of the public key. Only available on Android and Web.          | 0.1.0 |
| **`transports`**         | `PasskeyTransport[]` | The transports that the authenticator supports. Only available on Android and Web.           | 0.1.0 |

#### CreatePasskeyOptions

| Prop                         | Type                            | Description                                                                                                                                                                                  | Default  | Since |
| ---------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| **`attestation`**            | `PasskeyAttestation`            | The attestation conveyance preference.                                                                                                                                                       | `'none'` | 0.1.0 |
| **`authenticatorSelection`** | `PasskeyAuthenticatorSelection` | Criteria that the authenticator must meet.                                                                                                                                                   |          | 0.1.0 |
| **`challenge`**              | `string`                        | The challenge provided by the relying party server as a base64url-encoded string.                                                                                                            |          | 0.1.0 |
| **`excludeCredentials`**     | `PasskeyCredentialDescriptor[]` | Credentials that already exist for the user, so that the authenticator does not create a second passkey for the same account. On **iOS**, this option is only applied on iOS 17.4 and later. |          | 0.1.0 |
| **`pubKeyCredParams`**       | `PasskeyCredentialParameter[]`  | The public key credential types and algorithms that the relying party server supports, ordered from most to least preferred. Only available on Android and Web.                              |          | 0.1.0 |
| **`rp`**                     | `PasskeyRelyingParty`           | The relying party for which the passkey is created.                                                                                                                                          |          | 0.1.0 |
| **`timeout`**                | `number`                        | The time in milliseconds that the caller is willing to wait for the operation to complete. Only available on Android and Web.                                                                |          | 0.1.0 |
| **`user`**                   | `PasskeyUser`                   | The user account for which the passkey is created.                                                                                                                                           |          | 0.1.0 |

#### PasskeyAuthenticatorSelection

Criteria that the authenticator must meet to create a passkey.

| Prop                          | Type                             | Description                                                                                                                                                                                           | Default       | Since |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----- |
| **`authenticatorAttachment`** | `PasskeyAuthenticatorAttachment` | The authenticator attachment modality. Only available on Android and Web.                                                                                                                             |               | 0.1.0 |
| **`requireResidentKey`**      | `boolean`                        | Whether or not a discoverable credential (passkey) is required. This property is retained for backwards compatibility with WebAuthn Level 1. Prefer `residentKey`. Only available on Android and Web. |               | 0.1.0 |
| **`residentKey`**             | `PasskeyResidentKey`             | The extent to which the relying party desires to create a discoverable credential (passkey). Only available on Android and Web.                                                                       |               | 0.1.0 |
| **`userVerification`**        | `PasskeyUserVerification`        | The user verification requirement.                                                                                                                                                                    | `'preferred'` | 0.1.0 |

#### PasskeyCredentialDescriptor

A descriptor that identifies a specific credential.

| Prop             | Type                 | Description                                                                                          | Since |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`id`**         | `string`             | The credential identifier as a base64url-encoded string.                                             | 0.1.0 |
| **`transports`** | `PasskeyTransport[]` | The transports that the authenticator of the credential supports. Only available on Android and Web. | 0.1.0 |
| **`type`**       | `'public-key'`       | The credential type.                                                                                 | 0.1.0 |

#### PasskeyCredentialParameter

A public key credential type and algorithm that the relying party server supports.

| Prop       | Type           | Description                                                             | Since |
| ---------- | -------------- | ----------------------------------------------------------------------- | ----- |
| **`alg`**  | `number`       | The COSE algorithm identifier, e.g. `-7` for ES256 or `-257` for RS256. | 0.1.0 |
| **`type`** | `'public-key'` | The credential type.                                                    | 0.1.0 |

#### PasskeyRelyingParty

The relying party for which a passkey is created.

| Prop       | Type     | Description                                                                                                                                | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`id`**   | `string` | The identifier of the relying party. This must be a registrable domain suffix of (or equal to) the domain that the app is associated with. | 0.1.0 |
| **`name`** | `string` | The human-readable name of the relying party.                                                                                              | 0.1.0 |

#### PasskeyUser

The user account for which a passkey is created.

| Prop              | Type     | Description                                                                    | Since |
| ----------------- | -------- | ------------------------------------------------------------------------------ | ----- |
| **`displayName`** | `string` | The human-readable display name of the user account.                           | 0.1.0 |
| **`id`**          | `string` | The user handle of the user account as a base64url-encoded string.             | 0.1.0 |
| **`name`**        | `string` | The human-readable name of the user account, e.g. a username or email address. | 0.1.0 |

#### GetPasskeyResult

The result of the passkey authentication.

This mirrors the WebAuthn `AuthenticationResponseJSON` so it can be passed to any WebAuthn server library for verification.

| Prop                          | Type                             | Description                                                    | Since |
| ----------------------------- | -------------------------------- | -------------------------------------------------------------- | ----- |
| **`authenticatorAttachment`** | `PasskeyAuthenticatorAttachment` | The attachment of the authenticator that provided the passkey. | 0.1.0 |
| **`id`**                      | `string`                         | The credential identifier as a base64url-encoded string.       | 0.1.0 |
| **`rawId`**                   | `string`                         | The raw credential identifier as a base64url-encoded string.   | 0.1.0 |
| **`response`**                | `GetPasskeyResponse`             | The response of the authenticator.                             | 0.1.0 |
| **`type`**                    | `'public-key'`                   | The credential type.                                           | 0.1.0 |

#### GetPasskeyResponse

The response of the authenticator for the authentication with an existing passkey.

This mirrors the WebAuthn `AuthenticatorAssertionResponse` JSON serialization.

| Prop                    | Type     | Description                                                                             | Since |
| ----------------------- | -------- | --------------------------------------------------------------------------------------- | ----- |
| **`authenticatorData`** | `string` | The authenticator data as a base64url-encoded string.                                   | 0.1.0 |
| **`clientDataJSON`**    | `string` | The client data as a base64url-encoded string.                                          | 0.1.0 |
| **`signature`**         | `string` | The signature as a base64url-encoded string.                                            | 0.1.0 |
| **`userHandle`**        | `string` | The user handle (the `user.id` provided during creation) as a base64url-encoded string. | 0.1.0 |

#### GetPasskeyOptions

| Prop                   | Type                            | Description                                                                                                                                                            | Default       | Since |
| ---------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----- |
| **`allowCredentials`** | `PasskeyCredentialDescriptor[]` | The credentials that are acceptable to the relying party server. If not provided, the user can select from any discoverable credential (passkey) of the relying party. |               | 0.1.0 |
| **`challenge`**        | `string`                        | The challenge provided by the relying party server as a base64url-encoded string.                                                                                      |               | 0.1.0 |
| **`rpId`**             | `string`                        | The identifier of the relying party.                                                                                                                                   |               | 0.1.0 |
| **`timeout`**          | `number`                        | The time in milliseconds that the caller is willing to wait for the operation to complete. Only available on Android and Web.                                          |               | 0.1.0 |
| **`userVerification`** | `PasskeyUserVerification`       | The user verification requirement.                                                                                                                                     | `'preferred'` | 0.1.0 |

#### IsAvailableResult

| Prop            | Type      | Description                                           | Since |
| --------------- | --------- | ----------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not passkeys are available on this device. | 0.1.0 |

### Type Aliases

#### PasskeyAuthenticatorAttachment

The authenticator attachment modality.

`'cross-platform' | 'platform'`

#### PasskeyTransport

A transport that an authenticator supports.

`'ble' | 'hybrid' | 'internal' | 'nfc' | 'smart-card' | 'usb'`

#### PasskeyAttestation

The attestation conveyance preference.

`'direct' | 'enterprise' | 'indirect' | 'none'`

#### PasskeyResidentKey

The extent to which the relying party desires to create a discoverable credential (passkey).

`'discouraged' | 'preferred' | 'required'`

#### PasskeyUserVerification

The user verification requirement.

- `discouraged`: The relying party prefers no user verification.
- `preferred`: The relying party prefers user verification but will not fail the operation without it.
- `required`: The relying party requires user verification.

`'discouraged' | 'preferred' | 'required'`

## Testing

Keep the following in mind when testing your passkey integration:

- **Real device recommended**: Test on a real device with a screen lock set up. On iOS, the Simulator supports passkeys since iOS 16. On Android, the Emulator requires Google Play services and a Google account with Google Password Manager set up.
- **WebAuthn server**: The challenges in this plugin's examples are only placeholders. In production, the options must be generated and the results must be verified by a WebAuthn server library such as [SimpleWebAuthn](https://simplewebauthn.dev/) (Node.js) or [java-webauthn-server](https://github.com/Yubico/java-webauthn-server) (Java).
- **Domain association**: The relying party ID must be associated with your app (see the Installation section). Domain association changes can take some time to propagate, as the files are cached by Apple and Google.

## Limitations

Conditional UI (passkey autofill) is not supported by this plugin. The operating system autofill integrations target native text fields, not HTML inputs in a web view.

## FAQ

### How is this plugin different from other similar plugins?

It implements the full WebAuthn standard using the JSON serialization, so the options and results from any WebAuthn server library pass through unchanged on Android, iOS, and the Web. Passkey creation, authentication, and an `isAvailable()` capability check are all covered through a fully typed, actively maintained API. If you only need a local face or fingerprint check, a simpler biometric setup is enough; if you want to replace passwords with server-verified passkeys across every platform, this plugin is designed for exactly that.

### Why do the plugin methods reject with the `DOMAIN_NOT_ASSOCIATED` error code?

This error means that your app is not associated with the domain of the relying party (`rp.id` / `rpId`). On Android, you must host a Digital Asset Links file at `https://<your-domain>/.well-known/assetlinks.json` that delegates the `common.get_login_creds` permission to your app. On iOS, you must add the Associated Domains capability with the `webcredentials` service type and host a matching `apple-app-site-association` file. See the [Installation](#installation) section for the details. Also keep in mind that changes to these files can take some time to propagate, as they are cached by Apple and Google.

### Do I need my own WebAuthn server to use this plugin?

Yes. The challenges shown in the examples are only placeholders. In production, the options for `createPasskey(...)` and `getPasskey(...)` must be generated by a WebAuthn server, and the results must be verified by it, for example with a library such as [SimpleWebAuthn](https://simplewebauthn.dev/). Since the plugin uses the WebAuthn JSON serialization, any WebAuthn server library works unchanged.

### Which devices support passkeys?

On Android, passkeys are supported on Android 9 (API level 28) and higher with an available credential provider such as Google Password Manager. On iOS, passkeys are supported on iOS 15 and higher. On the web, passkeys are supported in browsers that implement WebAuthn with a user-verifying platform authenticator. Use the `isAvailable()` method to check the availability at runtime.

### Does this plugin support passkey autofill (Conditional UI)?

No, Conditional UI is not supported. The operating system autofill integrations target native text fields, not HTML inputs in a web view. See the [Limitations](#limitations) section for more details.

### What is the difference between this plugin and the Biometrics plugin?

The [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) plugin performs a local biometric check (e.g. face or fingerprint recognition) on the device, for example to protect a screen inside your app. The Passkeys plugin implements the WebAuthn standard, where the authentication is cryptographically verified by your server, making it suitable to replace password-based sign-in entirely.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face or fingerprint recognition.
- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers.
- [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/): Save passwords to the platform credential store.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords or tokens.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/passkeys/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/passkeys/LICENSE).

# Capacitor Password Autofill Plugin

Capacitor plugin for saving passwords to the platform credential store.

This plugin lets you **save into** the platform autofill system (iCloud Keychain on iOS, Google Password Manager on Android) after a successful in-app login. It does **not** fill forms — it solves the well-known problem that WebView-based apps never trigger the native "Save password?" prompt.

## Features

The Capacitor Password Autofill plugin is one of the most complete credential saving solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🔐 **Credential saving**: Save a username and password to the platform credential store.
- 🎯 **Deterministic**: Trigger the save prompt explicitly after a successful login, even for non-form flows.
- 🤝 **Compatibility**: Works alongside the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/), [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/) and [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Password Autofill plugin is typically used whenever an app wants credentials to end up in the platform credential store, for example:

- **Save credentials after login**: Trigger the native "Save password?" prompt after a successful in-app login, which WebView-based apps never trigger on their own.
- **Single-page app logins**: Save credentials for login flows based on `fetch()` and `preventDefault()`, which the operating system's form heuristics never detect.
- **Generated passwords**: Save automatically generated passwords, for example during a social signup flow without a login form.
- **Smoother re-logins**: Credentials saved to iCloud Keychain or Google Password Manager can be offered to the user again on future sign-ins.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-password-autofill` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-password-autofill
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxCredentialsVersion` version of `androidx.credentials:credentials` and `androidx.credentials:credentials-play-services-auth` (default: `1.5.0`)

No further setup is required. On Android, saving a credential presents the system "Save password?" prompt provided by the active credential provider (e.g. Google Password Manager).

### iOS

The Shared Web Credentials API requires the **Associated Domains** capability and a matching `apple-app-site-association` (AASA) file. Without this setup, `savePassword(...)` cannot save the credential.

#### Associated Domains

Add the Associated Domains entitlement to your app and include a `webcredentials:` entry for each domain you want to save credentials for:

```
<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:example.com</string>
</array>
```

The `domain` you pass to `savePassword(...)` must match one of these entries (without the `webcredentials:` prefix).

#### Apple App Site Association

Host an `apple-app-site-association` file at `https://example.com/.well-known/apple-app-site-association` that lists your app under the `webcredentials` service:

```
{
  "webcredentials": {
    "apps": ["TEAMID.com.example.app"]
  }
}
```

Replace `TEAMID` with your Apple Developer Team ID and `com.example.app` with your app's bundle identifier. See the [Apple documentation](https://developer.apple.com/documentation/xcode/supporting-associated-domains) for more information.

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to save a username and password to the platform credential store.

### Save a username and password

Call `savePassword(...)` after a successful login to save the credential to the platform credential store. On iOS, the `domain` is required and must match one of the domains in your app's Associated Domains entitlement (see [Installation](#installation)). On Android, the system "Save password?" prompt is presented to the user:

```
import { PasswordAutofill } from '@capawesome/capacitor-password-autofill';

const savePassword = async () => {
  await PasswordAutofill.savePassword({
    domain: 'example.com',
    username: 'jane.doe@example.com',
    password: 'super-secret',
  });
};
```

## API

- [`savePassword(...)`](#savepassword)
- [Interfaces](#interfaces)

### savePassword(...)

```
savePassword(options: SavePasswordOptions) => Promise<void>
```

Save a username and password to the platform credential store.

On iOS, the credential is saved to the iCloud Keychain via the Shared Web Credentials API. This requires the Associated Domains entitlement with a `webcredentials:` entry and a matching `apple-app-site-association` file hosted on your domain.

On Android, the credential is saved to the Google Password Manager (or another provider) via the Credential Manager API. This presents the system "Save password?" prompt to the user.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SavePasswordOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### SavePasswordOptions

| Prop           | Type     | Description                                                                                                                                                                                            | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`domain`**   | `string` | The domain to associate the credential with. This must match one of the domains in your app's Associated Domains entitlement (without the `webcredentials:` prefix). Only available on iOS (required). | 0.1.0 |
| **`password`** | `string` | The password to save.                                                                                                                                                                                  | 0.1.0 |
| **`username`** | `string` | The username to save.                                                                                                                                                                                  | 0.1.0 |

## When to use this plugin vs. the official guide

The [official Capacitor autofill guide](https://capacitorjs.com/docs/guides/autofill-credentials) saves credentials by relying on the operating system's form heuristics. This requires changing `server.hostname` to your real domain, which:

- changes the WebView origin and therefore wipes existing users' `localStorage`, `IndexedDB`, and cookies, and
- can break OAuth redirect allowlists.

It also depends on iOS detecting a form submission followed by a navigation — something typical single-page app logins (`fetch()` + `preventDefault()`) never trigger.

This plugin takes a different approach: **deterministic credential saving without changing the WebView origin**. Your app keeps `localhost` as its origin, and you call `savePassword(...)` explicitly after a successful login. This also covers non-form flows such as social signup with generated passwords.

What this plugin does **not** replace:

- The Associated Domains / `apple-app-site-association` setup is required in both approaches.
- Autofill (reading credentials back into a form) still benefits from the `autocomplete` attributes described in the official guide.

## FAQ

### How is this plugin different from other similar plugins?

It saves credentials into the platform credential store — iCloud Keychain on iOS and Google Password Manager on Android — with an explicit `savePassword(...)` call after a successful login. Because saving is triggered by an explicit call, it reliably covers single-page app logins built on `fetch()` and `preventDefault()` as well as non-form flows such as social signups with generated passwords, all without changing your WebView origin. The API is fully typed, supports both CocoaPods and Swift Package Manager on iOS, and is actively maintained against the latest Capacitor version.

### Does this plugin fill login forms with saved credentials?

No, this plugin only saves credentials into the platform autofill system (iCloud Keychain on iOS, Google Password Manager on Android). Filling credentials back into a form is handled by the operating system and still benefits from the `autocomplete` attributes described in the [official Capacitor autofill guide](https://capacitorjs.com/docs/guides/autofill-credentials).

### Why is the credential not saved on iOS?

The Shared Web Credentials API requires the Associated Domains capability with a `webcredentials:` entry and a matching `apple-app-site-association` file hosted on your domain. Without this setup, `savePassword(...)` cannot save the credential. Also make sure that the `domain` option matches one of the entries in your entitlement (without the `webcredentials:` prefix). See the [Installation](#installation) section for the details.

### Do I need to pass the `domain` option on Android?

No, the `domain` option is only used on iOS, where it is required and must match one of the domains in your app's Associated Domains entitlement. On Android, the credential is saved via the Credential Manager API without a domain.

### How is this plugin different from the official Capacitor autofill guide?

The [official guide](https://capacitorjs.com/docs/guides/autofill-credentials) relies on the operating system's form heuristics, which requires changing `server.hostname` to your real domain. This changes the WebView origin, wipes existing users' `localStorage`, `IndexedDB`, and cookies, and can break OAuth redirect allowlists. This plugin instead saves credentials deterministically with an explicit `savePassword(...)` call, so your app keeps `localhost` as its origin. See the [comparison section](#when-to-use-this-plugin-vs-the-official-guide) above for more details.

### Is this plugin available on the web?

No, this plugin is only available on Android and iOS. On the web, all methods reject as unimplemented.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face or fingerprint recognition.
- [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/password-autofill/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/password-autofill/LICENSE).

# Capacitor PDF Annotator Plugin

Capacitor plugin to annotate PDF documents in a fullscreen native viewer.

## Features

- ✍️ **Annotate**: Draw, highlight and erase on top of any PDF document with the native markup tools.
- ↩️ **Undo & Redo**: Undo and redo changes while annotating.
- 🖊️ **Apple Pencil**: Full Apple Pencil support on iPad.
- 💾 **Non-destructive**: The original file is never modified. Annotations are saved to a copy.
- ✅ **Availability Check**: Check whether annotation is supported on the current device.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The PDF Annotator plugin is typically used whenever users need to mark up a PDF document, for example:

- **Sheet music**: Let musicians write fingerings, breath marks or cues on their scores and highlight passages.
- **Document review**: Let users highlight sections and add handwritten remarks to contracts, reports or proofs.
- **Field work**: Let technicians draw on plans and inspection reports directly on site.
- **Education**: Let students and teachers annotate worksheets, handouts and exercises.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-pdf-annotator` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-pdf-annotator
npx cap sync
```

### Android

On Android, this plugin uses the [Jetpack PDF](https://developer.android.com/jetpack/androidx/releases/pdf) library, which provides a pen, a highlighter, an eraser and undo/redo. The annotation features of this library are currently in beta and marked as experimental by Google.

#### SDK Extension Level

The Jetpack PDF library requires your app to be compiled against Android SDK 36 with SDK extension level 19 or higher. Add the `compileSdkExtension` property to the `android` block of your app's `android/app/build.gradle` file:

```
android {
    compileSdk = rootProject.ext.compileSdkVersion
    compileSdkExtension = 19
    // ...
}
```

This requires the `Android SDK Platform 36-ext19` package. If it is not installed automatically during the build, install it via the SDK Manager of Android Studio (enable **Show Package Details** in the **SDK Platforms** tab) or by running the following command:

```
sdkmanager "platforms;android-36-ext19"
```

If your app is already compiled against Android SDK 37 or higher (requires Android Gradle Plugin 9.1 or higher), no extension level needs to be set.

#### Device Support

Annotating PDF documents requires Android 11 (API level 30) or higher and a PDF system module that supports annotations (SDK extension level 18 or higher). This module ships with Android 16 QPR2 and is delivered to older devices via Google Play system updates. Always check the availability with the `isAvailable()` method before calling `open(...)`.

#### Variables

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

- `$androidxPdfVersion` version of `androidx.pdf:pdf-ink` and `androidx.pdf:pdf-viewer-fragment` (default: `1.0.0-beta01`)
- `$androidxMaterialVersion` version of `com.google.android.material:material` (default: `1.13.0`)

### iOS

On iOS, this plugin uses the [Quick Look](https://developer.apple.com/documentation/quicklook) framework, which provides the system markup tools (pen, highlighter, pencil, eraser, shapes, text, signature and undo/redo) including Apple Pencil support. No additional configuration is required.

Be aware that the markup tools are not available on all simulator versions. Test the plugin on a real device.

### Web

This plugin is not available on the web.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check the availability, open a PDF document for annotation and keep the annotated file.

The plugin only supports local files. Remote URLs must be downloaded first, for example with the `downloadFile(...)` method of the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin.

### Check the availability

Check whether PDF annotation is supported on the current device before showing an annotation button to the user:

```
import { PdfAnnotator } from '@capawesome/capacitor-pdf-annotator';

const isAvailable = async () => {
  const { available } = await PdfAnnotator.isAvailable();
  return available;
};
```

### Annotate a PDF document

Open a local PDF file in a fullscreen native viewer that lets the user annotate it. The promise resolves with the path of the annotated copy when the user saves the annotations and closes the viewer. If the user closes the viewer without saving, the promise is rejected with the `CANCELED` error code. Only available on Android and iOS:

```
import { ErrorCode, PdfAnnotator } from '@capawesome/capacitor-pdf-annotator';

const open = async () => {
  try {
    const { path } = await PdfAnnotator.open({
      path: 'file:///path/to/document.pdf',
    });
    console.log('Annotated file: ', path);
  } catch (error) {
    if (error.code === ErrorCode.Canceled) {
      console.log('The user closed the viewer without saving.');
    }
  }
};
```

### Keep the annotated file

The annotated file is stored in the cache directory and deleted on the next app launch. Move it to a permanent location with the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin if you want to keep it:

```
import { Directory, Filesystem } from '@capacitor/filesystem';
import { PdfAnnotator } from '@capawesome/capacitor-pdf-annotator';

const annotateAndKeep = async () => {
  const { path } = await PdfAnnotator.open({
    path: 'file:///path/to/document.pdf',
  });
  await Filesystem.copy({
    from: path,
    to: 'annotated.pdf',
    toDirectory: Directory.Documents,
  });
};
```

## API

- [`isAvailable()`](#isavailable)
- [`open(...)`](#open)
- [Interfaces](#interfaces)

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check whether PDF annotation is available on this device.

On **Android**, this resolves to `true` if the device runs Android 11 (API level 30) or higher and its PDF system module supports annotations (SDK extension level 18 or higher). On **iOS**, this always resolves to `true`. On **Web**, this always resolves to `false`.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### open(...)

```
open(options: OpenOptions) => Promise<OpenResult>
```

Open a PDF file in a fullscreen native viewer that lets the user annotate it.

The promise resolves with the path of the annotated copy when the user saves the annotations and closes the viewer. If the user closes the viewer without saving, the promise is rejected with the `CANCELED` error code. The original file is never modified.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `OpenOptions` |

**Returns:** `Promise<OpenResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IsAvailableResult

| Prop            | Type      | Description                                                | Since |
| --------------- | --------- | ---------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not PDF annotation is available on this device. | 0.1.0 |

#### OpenResult

| Prop       | Type     | Description                                                                                                                                                                           | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path of the annotated copy of the PDF file. The file is stored in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it. | 0.1.0 |

#### OpenOptions

| Prop       | Type     | Description                                                                                                                                                                          | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`path`** | `string` | The path of the local PDF file to annotate. Remote URLs are not supported. Download the file first, for example to the cache directory, and pass the local file path to this method. | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It lets users draw, highlight and erase on top of a PDF document with the native markup tools of each platform, backed by Quick Look on iOS and the Jetpack PDF library on Android for a genuinely native annotation experience with undo/redo and Apple Pencil support. The original file is never touched: the annotated document is handed back as a separate file through a fully typed API that uses only official platform APIs. Actively maintained against the latest Capacitor version, it also pairs naturally with the PDF Viewer, PDF Generator and File Picker plugins.

### How is this plugin different from the PDF Viewer plugin?

The [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/) plugin is a lightweight, read-only viewer with paging, zoom and password support. The PDF Annotator plugin adds the native markup tools of each platform and returns the annotated document. Use the PDF Viewer plugin when users only need to read a document, and the PDF Annotator plugin when they need to mark it up.

### Why is annotation not available on my Android device?

On Android, annotating PDF documents requires Android 11 (API level 30) or higher and a PDF system module that supports annotations (SDK extension level 18 or higher). This module ships with Android 16 QPR2 and is delivered to older devices via Google Play system updates. Use the `isAvailable()` method to check the availability and hide the annotation feature on unsupported devices.

### Why do I need to set the SDK extension level on Android?

The Jetpack PDF library used by this plugin declares that depending apps must be compiled against an SDK with extension level 19 or higher. This is enforced by the Android Gradle Plugin, so the build fails without it. Android SDK 36 provides this extension level via the `android-36-ext19` platform (see [SDK Extension Level](#sdk-extension-level)). Changing the compile SDK does not change the runtime behavior of your app, which is controlled by the target SDK version.

### Can I customize the toolbar?

No, the plugin uses the system markup user interface of each platform, which can not be customized.

### Can I annotate a PDF from a remote URL?

No, the plugin only supports local files. Download the file first, for example with the `downloadFile(...)` method of the official [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin, and then pass the local file path to the `open(...)` method.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application instead of an in-app viewer.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a PDF file from the device's file system.
- [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/): Generate paginated PDF files from HTML content or URLs.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-annotator/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-annotator/LICENSE).

# Capacitor PDF Generator Plugin

Capacitor plugin to generate paginated PDF files from HTML content or URLs.

## Features

- 📄 **HTML to PDF**: Generate PDF files from HTML strings, for example invoices, tickets, and reports.
- 🌐 **URL to PDF**: Generate PDF files from web pages.
- 📃 **Pagination**: Real page breaks with selectable page sizes (A3, A4, A5, Letter) and orientation.
- 🖋️ **Vector Output**: Text stays selectable and sharp at any zoom level.
- 📂 **File Output**: Results are written to a file so even large documents don't exhaust memory.
- ⏱️ **Timeout**: Configurable timeout so hung pages never hang your app.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/), [Printer](https://capawesome.io/docs/sdks/capacitor/printer/) and [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The PDF Generator plugin is typically used whenever an app needs to produce a document on the device, for example:

- **Invoices and receipts**: Generate an invoice or receipt as a paginated PDF file from an HTML template.
- **Reports**: Export app data as a paginated report with real page breaks and selectable page sizes.
- **Tickets and confirmations**: Turn a booking confirmation or ticket into a PDF file that can be printed or shared.
- **Web page snapshots**: Save a web page as a PDF file by passing its URL to `generateFromUrl(...)`.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-pdf-generator` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-pdf-generator
npx cap sync
```

### Android

On Android, this plugin renders the HTML content in a hidden WebView and creates the PDF file with the [Android Print Framework](https://developer.android.com/training/printing). No additional configuration is required.

### iOS

On iOS, this plugin renders the HTML content in a hidden WKWebView and creates the PDF file with [UIKit](https://developer.apple.com/documentation/uikit). No additional configuration is required.

### Web

This plugin is not available on the web. Use `window.print()` with [print CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing) to let the user save a web page as a PDF file.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to generate a PDF file from HTML content and from a URL.

The generated PDF file is written to the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the `rename(...)` method of the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin. You can also hand the path to the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/), [Printer](https://capawesome.io/docs/sdks/capacitor/printer/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) or [Share](https://capacitorjs.com/docs/apis/share) plugin.

### Generate a PDF file from HTML content

Generate a paginated PDF file from an HTML string, with a custom file name, page size and orientation. Only available on Android and iOS:

```
import { PdfGenerator, Orientation, PageSize } from '@capawesome/capacitor-pdf-generator';

const generateFromHtml = async () => {
  const { path } = await PdfGenerator.generateFromHtml({
    html: '<h1>Invoice</h1><p>Thank you for your purchase!</p>',
    fileName: 'invoice.pdf',
    pageSize: PageSize.A4,
    orientation: Orientation.Portrait,
  });
  return path;
};
```

### Generate a PDF file from a URL

Generate a paginated PDF file from a web page. Use the `timeout` option to control how long the plugin waits for the page before the call is rejected with the `TIMEOUT` error code. Only available on Android and iOS:

```
import { PdfGenerator, Orientation, PageSize } from '@capawesome/capacitor-pdf-generator';

const generateFromUrl = async () => {
  const { path } = await PdfGenerator.generateFromUrl({
    url: 'https://capawesome.io/',
    pageSize: PageSize.Letter,
    orientation: Orientation.Landscape,
    timeout: 10000,
  });
  return path;
};
```

## API

- [`generateFromHtml(...)`](#generatefromhtml)
- [`generateFromUrl(...)`](#generatefromurl)
- [Interfaces](#interfaces)
- [Enums](#enums)

### generateFromHtml(...)

```
generateFromHtml(options: GenerateFromHtmlOptions) => Promise<GenerateResult>
```

Generate a paginated PDF file from an HTML string.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `GenerateFromHtmlOptions` |

**Returns:** `Promise<GenerateResult>`

**Since:** 0.1.0

______________________________________________________________________

### generateFromUrl(...)

```
generateFromUrl(options: GenerateFromUrlOptions) => Promise<GenerateResult>
```

Generate a paginated PDF file from a URL.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `GenerateFromUrlOptions` |

**Returns:** `Promise<GenerateResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GenerateResult

| Prop       | Type     | Description                                                                                                                                                               | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path of the generated PDF file. The file is stored in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it. | 0.1.0 |

#### GenerateFromHtmlOptions

| Prop              | Type          | Description                                                                                                                            | Default                           | Since |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----- |
| **`baseUrl`**     | `string`      | The base URL to resolve relative resources (e.g. images, stylesheets) in the HTML content against.                                     |                                   | 0.1.0 |
| **`fileName`**    | `string`      | The name of the generated PDF file. If the name does not end with `.pdf`, the extension is appended.                                   | `A randomly generated file name.` | 0.1.0 |
| **`html`**        | `string`      | The HTML content to generate the PDF file from.                                                                                        |                                   | 0.1.0 |
| **`orientation`** | `Orientation` | The page orientation of the generated PDF file.                                                                                        | `Orientation.Portrait`            | 0.1.0 |
| **`pageSize`**    | `PageSize`    | The page size of the generated PDF file.                                                                                               | `PageSize.A4`                     | 0.1.0 |
| **`timeout`**     | `number`      | The maximum time in milliseconds to wait for the PDF generation to complete before the call is rejected with the `TIMEOUT` error code. | `30000`                           | 0.1.0 |

#### GenerateFromUrlOptions

| Prop              | Type          | Description                                                                                                                            | Default                           | Since |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----- |
| **`fileName`**    | `string`      | The name of the generated PDF file. If the name does not end with `.pdf`, the extension is appended.                                   | `A randomly generated file name.` | 0.1.0 |
| **`orientation`** | `Orientation` | The page orientation of the generated PDF file.                                                                                        | `Orientation.Portrait`            | 0.1.0 |
| **`pageSize`**    | `PageSize`    | The page size of the generated PDF file.                                                                                               | `PageSize.A4`                     | 0.1.0 |
| **`timeout`**     | `number`      | The maximum time in milliseconds to wait for the PDF generation to complete before the call is rejected with the `TIMEOUT` error code. | `30000`                           | 0.1.0 |
| **`url`**         | `string`      | The URL of the web page to generate the PDF file from.                                                                                 |                                   | 0.1.0 |

### Enums

#### Orientation

| Members         | Value         | Description            | Since |
| --------------- | ------------- | ---------------------- | ----- |
| **`Landscape`** | `'LANDSCAPE'` | Landscape orientation. | 0.1.0 |
| **`Portrait`**  | `'PORTRAIT'`  | Portrait orientation.  | 0.1.0 |

#### PageSize

| Members      | Value      | Description              | Since |
| ------------ | ---------- | ------------------------ | ----- |
| **`A3`**     | `'A3'`     | ISO A3 (297 x 420 mm).   | 0.1.0 |
| **`A4`**     | `'A4'`     | ISO A4 (210 x 297 mm).   | 0.1.0 |
| **`A5`**     | `'A5'`     | ISO A5 (148 x 210 mm).   | 0.1.0 |
| **`Letter`** | `'LETTER'` | US Letter (8.5 x 11 in). | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It turns HTML content or a URL into a paginated PDF with real page breaks, selectable page sizes and orientation, and vector output so text stays sharp and selectable at any zoom. Results are written to a file rather than held in memory, so even large documents generate reliably, and a configurable timeout keeps a slow page from hanging your app — all through a fully typed API on Android and iOS using only official platform APIs. Actively maintained against the latest Capacitor version, it hands off cleanly to the PDF Viewer, Printer, and File Opener plugins.

### Where is the generated PDF file stored?

The generated PDF file is written to the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the `rename(...)` method of the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin.

### How can I display, print or share the generated PDF file?

The plugin returns the path of the generated file, which you can hand to other plugins: display it with the [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/) plugin, print it with the [Printer](https://capawesome.io/docs/sdks/capacitor/printer/) plugin, open it with the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) plugin, or share it with the [Share](https://capacitorjs.com/docs/apis/share) plugin.

### Is this plugin available on the web?

No, this plugin is only available on Android and iOS. On the web, use `window.print()` with [print CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing) to let the user save a web page as a PDF file.

### Why does the call reject with the `TIMEOUT` error code?

The PDF generation did not complete within the configured timeout, for example because the web page did not finish loading. By default, the plugin waits 30000 milliseconds. Increase the `timeout` option if your content needs more time to load.

### Which page sizes and orientations are supported?

The plugin supports the page sizes A3, A4, A5 and US Letter in portrait or landscape orientation. The page size defaults to A4 and the orientation defaults to portrait.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application.
- [PDF Annotator](https://capawesome.io/docs/sdks/capacitor/pdf-annotator/): Let the user annotate PDF documents with the native markup tools.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer.
- [Printer](https://capawesome.io/docs/sdks/capacitor/printer/): Print HTML, PDFs, files and more on Android and iOS.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-generator/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-generator/LICENSE).

# Capacitor PDF Viewer Plugin

Capacitor plugin to display PDF documents in a fullscreen native viewer.

## Features

- 📄 **Fullscreen Viewer**: Display PDF documents in a fullscreen native viewer with a toolbar.
- 📖 **Paging**: Scroll through pages and jump to an initial page.
- 🔍 **Zoom**: Pinch to zoom in and out.
- 🔑 **Password Protection**: Open password-protected PDF documents.
- 🔔 **Events**: Listen for page changes and the closing of the viewer.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The PDF Viewer plugin is typically used whenever an app needs to present a PDF document to the user, for example:

- **Invoices and receipts**: Display invoices or receipts that your app has generated or downloaded.
- **Reports and manuals**: Let users read reports, product manuals, or other multi-page documents with paging and zoom.
- **Confidential documents**: Open password-protected PDF documents such as payslips or bank statements.
- **Reading progress**: Use the `pageChange` event to remember the last read page and reopen the document there via the `page` option.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-pdf-viewer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-pdf-viewer
npx cap sync
```

### Android

On Android, this plugin uses the [android-pdf-viewer](https://github.com/oothp/AndroidPdfViewer) library, which renders PDF documents with [Pdfium](https://pdfium.googlesource.com/pdfium/). Be aware that the library bundles the Pdfium native libraries, which add about 10 to 16 MB (uncompressed, across all ABIs) to your app. If you publish your app as an [Android App Bundle](https://developer.android.com/guide/app-bundle), each device only downloads the native libraries for its own ABI, which significantly reduces the download size. Also note that the viewer does not support text selection on Android.

#### Share Button

If you use the share button (see the `showShareButton` option), you need to specify the directories that contain the PDF files you want to share. To do this, create a new file named `file_paths.xml` in the `res/xml` directory of your Android project (e.g. `android/app/src/main/res/xml/file_paths.xml`). Here is an example of the content of the file:

```
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="files" path="." />
    <cache-path name="cache" path="." />
    <external-files-path name="external-files" path="." />
    <external-cache-path name="external-cache" path="." />
    <external-path name="external" path="." />
</paths>
```

More information can be found in the [Android documentation](https://developer.android.com/training/secure-file-sharing/setup-sharing#DefineMetaData).

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$androidPdfViewerVersion` version of `io.github.oothp:android-pdf-viewer` (default: `3.2.0-beta06`)

### iOS

On iOS, this plugin uses the [PDFKit](https://developer.apple.com/documentation/pdfkit) framework. No additional configuration is required.

### Web

This plugin is not available on the web. Browsers ship with a built-in PDF viewer, so you can simply render a PDF document using an `<iframe>` or `<object>` element.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to open a PDF document, unlock a password-protected file, close the viewer, and listen for page changes and the viewer being closed.

The plugin only supports local files. Remote URLs must be downloaded first, for example with the `downloadFile(...)` method of the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin.

### Open a PDF document

Open a local PDF file in a fullscreen native viewer. You can set a custom toolbar title and the page to display initially. Only available on Android and iOS:

```
import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const open = async () => {
  await PdfViewer.open({
    path: 'file:///path/to/document.pdf',
    title: 'Invoice',
    page: 1,
  });
};
```

### Open a password-protected PDF document

Use the `password` option to unlock a password-protected PDF file:

```
import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const openWithPassword = async () => {
  await PdfViewer.open({
    path: 'file:///path/to/document.pdf',
    password: 'secret',
  });
};
```

### Close the viewer

Close the currently open viewer from code. If no viewer is open, this method does nothing:

```
import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const close = async () => {
  await PdfViewer.close();
};
```

### Listen for page changes and the viewer being closed

Use the `pageChange` and `closed` events to react to the user scrolling through the document or closing the viewer:

```
import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const addListeners = async () => {
  await PdfViewer.addListener('closed', () => {
    console.log('Viewer closed');
  });
  await PdfViewer.addListener('pageChange', event => {
    console.log('Current page:', event.page);
  });
};
```

## API

- [`close()`](#close)
- [`open(...)`](#open)
- [`addListener('closed', ...)`](#addlistenerclosed-)
- [`addListener('pageChange', ...)`](#addlistenerpagechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### close()

```
close() => Promise<void>
```

Close the currently open viewer.

If no viewer is open, this method does nothing.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### open(...)

```
open(options: OpenOptions) => Promise<void>
```

Open a PDF file in a fullscreen native viewer.

If a viewer is already open, it is closed before the new one is presented.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `OpenOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('closed', ...)

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

Called when the viewer is closed.

Only available on Android and iOS.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'closed'`   |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('pageChange', ...)

```
addListener(eventName: 'pageChange', listenerFunc: (event: PageChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the current page of the viewer changes.

Only available on Android and iOS.

| Param              | Type                               |
| ------------------ | ---------------------------------- |
| **`eventName`**    | `'pageChange'`                     |
| **`listenerFunc`** | `(event: PageChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### OpenOptions

| Prop                  | Type      | Description                                                                                                                                                                         | Default                          | Since |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----- |
| **`page`**            | `number`  | The page (1-based) to display initially.                                                                                                                                            | `1`                              | 0.1.0 |
| **`password`**        | `string`  | The password to unlock the PDF file if it is password-protected.                                                                                                                    |                                  | 0.1.0 |
| **`path`**            | `string`  | The path of the local PDF file to display. Remote URLs are not supported. Download the file first, for example to the cache directory, and pass the local file path to this method. |                                  | 0.1.0 |
| **`showShareButton`** | `boolean` | Whether to display a share button in the toolbar of the viewer. Only available on Android and iOS.                                                                                  | `false`                          | 0.1.2 |
| **`title`**           | `string`  | The title to display in the toolbar of the viewer.                                                                                                                                  | `The file name of the PDF file.` | 0.1.0 |

#### PluginListenerHandle

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

#### PageChangeEvent

| Prop       | Type     | Description                                     | Since |
| ---------- | -------- | ----------------------------------------------- | ----- |
| **`page`** | `number` | The page (1-based) that is currently displayed. | 0.1.0 |

## FAQ

### How is this plugin different from other similar plugins?

It displays PDF documents in a fullscreen native viewer with a toolbar, paging, pinch-to-zoom, and support for password-protected files, backed by PDFKit on iOS and Pdfium on Android for a genuinely native reading experience. Page-change and closed events let you track reading progress and reopen a document where the user left off, all through a fully typed API that uses only official platform APIs. Actively maintained against the latest Capacitor version, it also pairs naturally with the PDF Generator and File Picker plugins.

### Can I display a PDF from a remote URL?

No, the plugin only supports local files. Download the file first, for example with the `downloadFile(...)` method of the official [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin, and then pass the local file path to the `open(...)` method.

### Why is the plugin not available on the Web?

Browsers ship with a built-in PDF viewer, so a plugin is not needed there. On the Web, you can simply render a PDF document using an `<iframe>` or `<object>` element.

### How do I open a password-protected PDF document?

Pass the password using the `password` option of the `open(...)` method. The viewer then unlocks and displays the document. See [Open a password-protected PDF document](#open-a-password-protected-pdf-document) for an example.

### How much does the plugin add to my Android app size?

On Android, the plugin uses the [android-pdf-viewer](https://github.com/oothp/AndroidPdfViewer) library, which bundles the Pdfium native libraries. These add about 10 to 16 MB (uncompressed, across all ABIs) to your app. If you publish your app as an Android App Bundle, each device only downloads the native libraries for its own ABI, which significantly reduces the download size.

### Can I select text in the viewer on Android?

No, the viewer does not support text selection on Android. On iOS, the plugin uses the PDFKit framework, which provides the native viewer experience of the platform.

### Why does the share button not work on Android?

The share button is hidden by default. Enable it by setting the `showShareButton` option to `true`. On Android, the file is then shared using a [`FileProvider`](https://developer.android.com/reference/androidx/core/content/FileProvider). Make sure that the directory containing the PDF file is declared in the `file_paths.xml` file of your Android project, as described in the [Installation](#android) section. Without this configuration, the file can not be shared.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application instead of an in-app viewer.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a PDF file from the device's file system.
- [PDF Annotator](https://capawesome.io/docs/sdks/capacitor/pdf-annotator/): Let the user annotate PDF documents with the native markup tools.
- [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/): Generate paginated PDF files from HTML content or URLs.
- [Printer](https://capawesome.io/docs/sdks/capacitor/printer/): Print PDF documents on Android and iOS.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-viewer/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pdf-viewer/LICENSE).

# Capacitor Pedometer Plugin

Capacitor plugin to retrieve motion data, such as the number of steps and other information about the distance traveled.

## Features

The Capacitor Pedometer plugin is one of the most complete motion tracking solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🚶 **Motion Tracking**: Retrieve step count, distance, pace, cadence, and floor counting data.
- 📊 **Real-time Updates**: Stream live pedometer data with event listeners for continuous monitoring.
- 📅 **Historical Data**: Query pedometer measurements for specific time ranges and periods.
- 🔍 **Feature Detection**: Check device capability for different pedometer features (steps, distance, floors, etc.).
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/) and [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Pedometer plugin is typically used whenever an app needs to track the user's physical activity, for example:

- **Fitness and step tracking**: Show the user's step count in a health or fitness app.
- **Workout sessions**: Stream live pedometer data with the `measurement` event to display real-time progress during a walk or run.
- **Distance and pace insights**: Display the distance traveled, current pace, and cadence of the user on iOS.
- **Floor climbing challenges**: Count the floors ascended and descended by the user on iOS.
- **Activity history**: Query pedometer measurements for a specific time range to build daily or weekly summaries.

## Compatibility

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

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): Fitness-tracking use cases and how this plugin compares to the raw Accelerometer.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-pedometer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-pedometer
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSMotionUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts:

```
<key>NSMotionUsageDescription</key>
<string>The app needs to access the motion activity.</string>
```

## Usage

The following examples show how to check which pedometer features are available, retrieve a measurement, receive live measurement updates, and check and request permissions.

### Check which features are available

Not every device supports every pedometer feature. Use `isAvailable()` to check whether step counting, distance tracking, pace, cadence, and floor counting are supported before relying on them:

```
import { Pedometer } from '@capawesome-team/capacitor-pedometer';

const isAvailable = async () => {
  const { cadence, distance, floorCounting, pace, stepCounting } = await Pedometer.isAvailable();
  console.log('Cadence available:', cadence);
  console.log('Distance available:', distance);
  console.log('Floor counting available:', floorCounting);
  console.log('Pace available:', pace);
  console.log('Step counting available:', stepCounting);
};
```

### Retrieve a pedometer measurement

Retrieve the pedometer data, such as the number of steps taken by the user. On iOS, you must provide the `start` and `end` options to query a specific time range. Only available on Android and iOS:

```
import { Pedometer } from '@capawesome-team/capacitor-pedometer';

const getMeasurement = async () => {
  const { measurement } = await Pedometer.getMeasurement();
  console.log(measurement);
};
```

### Receive live measurement updates

Add a listener for the `measurement` event and call `startMeasurementUpdates()` to continuously receive pedometer data, for example during a workout session. Call `stopMeasurementUpdates()` when you no longer need updates. Only available on Android and iOS:

```
import { Pedometer } from '@capawesome-team/capacitor-pedometer';

const startMeasurementUpdates = async () => {
  Pedometer.addListener('measurement', (event) => {
    console.log('New measurement:', event);
  });
  await Pedometer.startMeasurementUpdates();
};

const stopMeasurementUpdates = async () => {
  await Pedometer.stopMeasurementUpdates();
};
```

### Check and request permissions

Check and request the permission for the activity recognition feature before accessing pedometer data:

```
import { Pedometer } from '@capawesome-team/capacitor-pedometer';

const checkPermissions = async () => {
  const status = await Pedometer.checkPermissions();
  console.log('Permission status:', status);
};

const requestPermissions = async () => {
  const status = await Pedometer.requestPermissions();
  console.log('Permission status after request:', status);
};
```

## API

- [`getMeasurement(...)`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getMeasurement(...)

```
getMeasurement(options?: GetMeasurementOptions | undefined) => Promise<GetMeasurementResult>
```

Retrieve the pedometer data (for a specific time range).

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetMeasurementOptions` |

**Returns:** `Promise<Measurement>`

**Since:** 7.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check which features are available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 7.0.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Start receiving updates for the pedometer data.

Only available on Android and iOS.

**Since:** 7.0.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stop receiving updates for the pedometer data.

Only available on Android and iOS.

**Since:** 7.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for the plugin.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permissions for the plugin.

**Returns:** `Promise<PermissionStatus>`

**Since:** 7.0.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Called when the pedometer data is updated.

When the app is suspended, the delivery of updates stops temporarily. When the app is resumed, the updates will continue from where they left off.

**Note:** The `startMeasurementUpdates` method must be called before this event can be received.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 7.0.0

______________________________________________________________________

### Interfaces

#### Measurement

| Prop                    | Type     | Description                                                                                                                | Since |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`averageActivePace`** | `number` | The average pace of the user, measured in seconds per meter. Only available on iOS.                                        | 7.0.0 |
| **`currentCadence`**    | `number` | The rate at which steps are taken, measured in steps per second. Only available on iOS.                                    | 7.0.0 |
| **`currentPace`**       | `number` | The current pace of the user, measured in seconds per meter. Only available on iOS.                                        | 7.0.0 |
| **`distance`**          | `number` | The estimated distance traveled by the user, measured in meters. Only available on iOS.                                    | 7.0.0 |
| **`end`**               | `number` | The end date of the data in milliseconds since epoch.                                                                      | 7.0.0 |
| **`floorsAscended`**    | `number` | The number of floors ascended by the user. Only available on iOS.                                                          | 7.0.0 |
| **`floorsDescended`**   | `number` | The number of floors descended by the user. Only available on iOS.                                                         | 7.0.0 |
| **`numberOfSteps`**     | `number` | The number of steps taken by the user.                                                                                     | 7.0.0 |
| **`start`**             | `number` | The start date of the data in milliseconds since epoch. On **Android**, this is always set to the boot time of the device. | 7.0.0 |

#### GetMeasurementOptions

| Prop        | Type     | Description                                                                                                                                                                                   | Since |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`end`**   | `number` | The end date for the query in milliseconds since epoch. On **iOS**, this option must be provided. Only available on iOS.                                                                      | 7.0.0 |
| **`start`** | `number` | The start date for the query in milliseconds since epoch. On **Android**, this is always set to the boot time of the device. On **iOS**, this option must be provided. Only available on iOS. | 7.0.0 |

#### IsAvailableResult

| Prop                | Type      | Description                                                                                                                                        | Since |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`cadence`**       | `boolean` | Indicates whether cadence tracking is available on the device. On **Android**, this is always `false` because cadence tracking is not supported.   | 7.0.0 |
| **`distance`**      | `boolean` | Indicates whether distance tracking is available on the device. On **Android**, this is always `false` because distance tracking is not supported. | 7.0.0 |
| **`floorCounting`** | `boolean` | Indicates whether floor counting is available on the device. On **Android**, this is always `false` because floor counting is not supported.       | 7.0.0 |
| **`pace`**          | `boolean` | Indicates whether pace tracking is available on the device. On **Android**, this is always `false` because pace tracking is not supported.         | 7.0.0 |
| **`stepCounting`**  | `boolean` | Indicates whether step counting is available on the device.                                                                                        | 7.0.0 |

#### PermissionStatus

| Prop                      | Type              | Description                                                | Since |
| ------------------------- | ----------------- | ---------------------------------------------------------- | ----- |
| **`activityRecognition`** | `PermissionState` | The permission state for the activity recognition feature. | 7.0.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetMeasurementResult

`Measurement`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### MeasurementEvent

`Measurement`

## FAQ

### Does the plugin work on the web?

No, the plugin only supports Android and iOS. The pedometer methods such as `getMeasurement(...)` and `startMeasurementUpdates()` rely on the native motion APIs of the device and are therefore not available on the web.

### Why are distance, pace, cadence, and floor counts missing on Android?

On Android, only step counting is supported. Distance tracking, pace, cadence, and floor counting are only available on iOS. You can use the `isAvailable()` method to check at runtime which features are supported on the current device, as shown in the [usage example](#check-which-features-are-available) above.

### Do I need any permissions to use the plugin?

Yes. The plugin provides the `checkPermissions()` and `requestPermissions()` methods to check and request the permission for the activity recognition feature. On iOS, you also need to add the `NSMotionUsageDescription` key to your `Info.plist` file, as described in the [Installation](#installation) section.

### Can I query pedometer data for a specific time range?

Yes, the `getMeasurement(...)` method accepts `start` and `end` options in milliseconds since epoch. On iOS, both options must be provided. On Android, the start date is always set to the boot time of the device.

### Why do I stop receiving measurement events while the app is suspended?

When the app is suspended, the delivery of updates stops temporarily. When the app is resumed, the updates will continue from where they left off. Also note that the `startMeasurementUpdates()` method must be called before the `measurement` event can be received.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure measured in hectopascals.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pedometer/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pedometer/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/pedometer/LICENSE).

# Capacitor Permissions Plugin

Capacitor plugin to check and request device permissions with a unified API.

## Features

- 🖥️ **Cross-platform**: Supports Android, iOS and Web (partial).
- 🧩 **Unified API**: Check and request many different permissions with a single API instead of installing a feature plugin for each one.
- 🗂️ **Curated catalog**: Supports Bluetooth, calendar, camera, contacts, location, background location, microphone, motion, notifications, photos and reminders.
- 🔍 **Prompt-free checks**: The `check(...)` method never triggers a permission prompt.
- 🪶 **Lightweight**: The plugin does not declare any permissions itself. Your app only declares the permissions it actually uses.
- 🤝 **Compatibility**: Works alongside the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) and [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Permissions plugin is typically used whenever an app needs to manage several device permissions in one place, for example:

- **Onboarding screens**: Check the states of all permissions your app uses with the prompt-free `check(...)` method and present them in a single overview.
- **Contextual permission requests**: Request the camera or microphone permission right before the user starts a video call or recording.
- **Background location upgrades**: Request the `LOCATION` permission first and upgrade to `LOCATION_ALWAYS` afterwards, as recommended by the platforms.
- **Recovering from denied permissions**: Detect the `denied` state and guide the user to the app settings to re-enable the permission.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-permissions` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-permissions
npx cap sync
```

**Attention**: The plugin itself does **not** declare any permissions and does **not** require any Info.plist keys. Your app must declare exactly the permissions it actually uses (see below). This way, your app does not request permissions it does not need.

### Android

#### Permissions

Add the manifest entries for the permissions you want to check or request to your `AndroidManifest.xml` file before or after the `application` tag. If a permission is not declared, the `request(...)` method rejects with a clear error message.

| Permission        | Required manifest entries                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BLUETOOTH`       | `android.permission.BLUETOOTH_SCAN`, `android.permission.BLUETOOTH_CONNECT`                                                                                     |
| `CALENDAR`        | `android.permission.READ_CALENDAR`, `android.permission.WRITE_CALENDAR`                                                                                         |
| `CAMERA`          | `android.permission.CAMERA`                                                                                                                                     |
| `CONTACTS`        | `android.permission.READ_CONTACTS`, `android.permission.WRITE_CONTACTS`                                                                                         |
| `LOCATION`        | `android.permission.ACCESS_COARSE_LOCATION`, `android.permission.ACCESS_FINE_LOCATION`                                                                          |
| `LOCATION_ALWAYS` | `android.permission.ACCESS_BACKGROUND_LOCATION` (plus the `LOCATION` entries)                                                                                   |
| `MICROPHONE`      | `android.permission.RECORD_AUDIO`                                                                                                                               |
| `MOTION`          | `android.permission.ACTIVITY_RECOGNITION`                                                                                                                       |
| `NOTIFICATIONS`   | `android.permission.POST_NOTIFICATIONS`                                                                                                                         |
| `PHOTOS`          | `android.permission.READ_MEDIA_IMAGES`, `android.permission.READ_MEDIA_VISUAL_USER_SELECTED`, `android.permission.READ_EXTERNAL_STORAGE` (max SDK version `32`) |
| `REMINDERS`       | Not available on Android.                                                                                                                                       |

**Example**:

```
<!-- Required if you want to use the `BLUETOOTH` permission. -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- Required if you want to use the `CALENDAR` permission. -->
<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
<!-- Required if you want to use the `CAMERA` permission. -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- Required if you want to use the `CONTACTS` permission. -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<!-- Required if you want to use the `LOCATION` or `LOCATION_ALWAYS` permission. -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Required if you want to use the `LOCATION_ALWAYS` permission. -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<!-- Required if you want to use the `MICROPHONE` permission. -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- Required if you want to use the `MOTION` permission. -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<!-- Required if you want to use the `NOTIFICATIONS` permission. -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- Required if you want to use the `PHOTOS` permission. -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
```

### iOS

#### Privacy Descriptions

Add the usage description keys for the permissions you want to request to the `ios/App/App/Info.plist` file. If a key is missing, the `request(...)` method rejects with a clear error message.

| Permission        | Required Info.plist keys                                                                            |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `BLUETOOTH`       | `NSBluetoothAlwaysUsageDescription`                                                                 |
| `CALENDAR`        | `NSCalendarsFullAccessUsageDescription` (iOS 17+), `NSCalendarsUsageDescription` (iOS 16 and older) |
| `CAMERA`          | `NSCameraUsageDescription`                                                                          |
| `CONTACTS`        | `NSContactsUsageDescription`                                                                        |
| `LOCATION`        | `NSLocationWhenInUseUsageDescription`                                                               |
| `LOCATION_ALWAYS` | `NSLocationAlwaysAndWhenInUseUsageDescription`, `NSLocationWhenInUseUsageDescription`               |
| `MICROPHONE`      | `NSMicrophoneUsageDescription`                                                                      |
| `MOTION`          | `NSMotionUsageDescription`                                                                          |
| `NOTIFICATIONS`   | None                                                                                                |
| `PHOTOS`          | `NSPhotoLibraryUsageDescription`                                                                    |
| `REMINDERS`       | `NSRemindersFullAccessUsageDescription` (iOS 17+), `NSRemindersUsageDescription` (iOS 16 and older) |

**Example**:

```
<key>NSCameraUsageDescription</key>
<string>The camera is used to take photos.</string>
<key>NSMicrophoneUsageDescription</key>
<string>The microphone is used to record audio.</string>
```

**Note**: Since the plugin references the system frameworks of all supported permissions, App Store Connect may ask you to provide additional usage descriptions when you upload your app, even if you do not request those permissions.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check the states of one or more permissions and how to request them from the user.

### Check the states of one or more permissions

Use the `check(...)` method to read the current states of one or more permissions. This method never displays a permission prompt, so it is safe to call at any time, for example to build an onboarding or settings screen:

```
import { Permission, Permissions } from '@capawesome/capacitor-permissions';

const checkPermissions = async () => {
  const { statuses } = await Permissions.check({
    permissions: [Permission.Camera, Permission.Microphone],
  });
  return statuses;
};
```

### Request one or more permissions

Use the `request(...)` method to prompt the user for one or more permissions. Permissions that are already granted or that cannot be requested on the current platform are not requested again; in that case, the current state is returned. On the web, only the `NOTIFICATIONS` permission can be requested:

```
import { Permission, Permissions } from '@capawesome/capacitor-permissions';

const requestPermissions = async () => {
  const { statuses } = await Permissions.request({
    permissions: [Permission.Camera, Permission.Microphone],
  });
  return statuses;
};
```

## API

- [`check(...)`](#check)
- [`request(...)`](#request)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### check(...)

```
check(options: CheckOptions) => Promise<CheckResult>
```

Check the current states of one or more permissions.

This method never displays a permission prompt.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `CheckOptions` |

**Returns:** `Promise<CheckResult>`

**Since:** 0.1.0

______________________________________________________________________

### request(...)

```
request(options: RequestOptions) => Promise<RequestResult>
```

Request one or more permissions from the user.

Permissions that are already granted or that cannot be requested on the current platform are not requested again. In this case, the current state of the permission is returned.

On Android, the corresponding permissions must be declared in the `AndroidManifest.xml` file of your app. Otherwise, the call is rejected.

On iOS, the corresponding usage descriptions must be provided in the `Info.plist` file of your app. Otherwise, the call is rejected.

On the web, only the `NOTIFICATIONS` permission can be requested. For all other permissions, the current state is returned since browsers display the permission prompt when the corresponding web API is used for the first time.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `RequestOptions` |

**Returns:** `Promise<RequestResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CheckResult

| Prop           | Type                 | Description                                                                          | Since |
| -------------- | -------------------- | ------------------------------------------------------------------------------------ | ----- |
| **`statuses`** | `PermissionStatus[]` | The states of the checked permissions in the same order as the provided permissions. | 0.1.0 |

#### PermissionStatus

| Prop             | Type              | Description                                   | Since |
| ---------------- | ----------------- | --------------------------------------------- | ----- |
| **`permission`** | `Permission`      | The permission that was checked or requested. | 0.1.0 |
| **`state`**      | `PermissionState` | The state of the permission.                  | 0.1.0 |

#### CheckOptions

| Prop              | Type           | Description               | Since |
| ----------------- | -------------- | ------------------------- | ----- |
| **`permissions`** | `Permission[]` | The permissions to check. | 0.1.0 |

#### RequestResult

| Prop           | Type                 | Description                                                                            | Since |
| -------------- | -------------------- | -------------------------------------------------------------------------------------- | ----- |
| **`statuses`** | `PermissionStatus[]` | The states of the requested permissions in the same order as the provided permissions. | 0.1.0 |

#### RequestOptions

| Prop              | Type           | Description                 | Since |
| ----------------- | -------------- | --------------------------- | ----- |
| **`permissions`** | `Permission[]` | The permissions to request. | 0.1.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### Permission

| Members              | Value               | Description                                                                                                                                                                                                                                                                                             | Since |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Bluetooth`**      | `'BLUETOOTH'`       | [Permission](#permission) to use Bluetooth. On Android 12 (API level 31) and later, this covers the `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` permissions. On older Android versions, no runtime permission is required and the state is always `granted`. On the web, this permission is not available. | 0.1.0 |
| **`Calendar`**       | `'CALENDAR'`        | [Permission](#permission) to read and write calendar events. On iOS 17 and later, write-only access is reported as `limited`. On the web, this permission is not available.                                                                                                                             | 0.1.0 |
| **`Camera`**         | `'CAMERA'`          | [Permission](#permission) to use the camera.                                                                                                                                                                                                                                                            | 0.1.0 |
| **`Contacts`**       | `'CONTACTS'`        | [Permission](#permission) to read and write contacts. On iOS 18 and later, limited access is reported as `limited`. On the web, this permission is not available.                                                                                                                                       | 0.1.0 |
| **`Location`**       | `'LOCATION'`        | [Permission](#permission) to access the location while the app is in use. On Android 12 (API level 31) and later, the user may grant only approximate location access. In this case, the state is still reported as `granted`.                                                                          | 0.1.0 |
| **`LocationAlways`** | `'LOCATION_ALWAYS'` | [Permission](#permission) to access the location even while the app is in the background. This permission should only be requested after the `LOCATION` permission has been granted. On the web, this permission is not available.                                                                      | 0.1.0 |
| **`Microphone`**     | `'MICROPHONE'`      | [Permission](#permission) to use the microphone.                                                                                                                                                                                                                                                        | 0.1.0 |
| **`Motion`**         | `'MOTION'`          | [Permission](#permission) to access motion and fitness data. On Android 10 (API level 29) and later, this covers the `ACTIVITY_RECOGNITION` permission. On older Android versions, no runtime permission is required and the state is always `granted`. On the web, this permission is not available.   | 0.1.0 |
| **`Notifications`**  | `'NOTIFICATIONS'`   | [Permission](#permission) to display notifications. On Android 13 (API level 33) and later, this covers the `POST_NOTIFICATIONS` permission. On older Android versions, no runtime permission is required and the state is always `granted`.                                                            | 0.1.0 |
| **`Photos`**         | `'PHOTOS'`          | [Permission](#permission) to access the photo library. On Android 14 (API level 34) and later and on iOS, partial access to the photo library is reported as `limited`. On the web, this permission is not available.                                                                                   | 0.1.0 |
| **`Reminders`**      | `'REMINDERS'`       | [Permission](#permission) to read and write reminders. Only available on iOS.                                                                                                                                                                                                                           | 0.1.0 |

## Platform behavior

The following table summarizes the behavior of each permission on each platform:

| Permission        | Android                                                                                                                                                                   | iOS                                                                                  | Web                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `BLUETOOTH`       | Covers `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` on Android 12+. On older versions, always `granted`.                                                                      | Covers the Core Bluetooth authorization.                                             | Always `unavailable`.                               |
| `CALENDAR`        | Covers `READ_CALENDAR` and `WRITE_CALENDAR`.                                                                                                                              | On iOS 17+, write-only access is reported as `limited`.                              | Always `unavailable`.                               |
| `CAMERA`          | Covers `CAMERA`.                                                                                                                                                          | Covers the camera authorization.                                                     | Check supported. Request returns the current state. |
| `CONTACTS`        | Covers `READ_CONTACTS` and `WRITE_CONTACTS`.                                                                                                                              | On iOS 18+, limited access is reported as `limited`.                                 | Always `unavailable`.                               |
| `LOCATION`        | Covers `ACCESS_COARSE_LOCATION` and `ACCESS_FINE_LOCATION`. Reported as `granted` if at least approximate location access has been granted.                               | Covers the when-in-use location authorization.                                       | Check supported. Request returns the current state. |
| `LOCATION_ALWAYS` | Covers `ACCESS_BACKGROUND_LOCATION` on Android 10+. On older versions, behaves like `LOCATION`.                                                                           | Covers the always location authorization. iOS only displays the upgrade prompt once. | Always `unavailable`.                               |
| `MICROPHONE`      | Covers `RECORD_AUDIO`.                                                                                                                                                    | Covers the microphone authorization.                                                 | Check supported. Request returns the current state. |
| `MOTION`          | Covers `ACTIVITY_RECOGNITION` on Android 10+. On older versions, always `granted`.                                                                                        | Covers the motion activity authorization. Requires a real device.                    | Always `unavailable`.                               |
| `NOTIFICATIONS`   | Covers `POST_NOTIFICATIONS` on Android 13+. On older versions, always `granted`.                                                                                          | Covers the notifications authorization.                                              | Check and request supported.                        |
| `PHOTOS`          | Covers `READ_MEDIA_IMAGES` (and `READ_MEDIA_VISUAL_USER_SELECTED`) on Android 13+ and `READ_EXTERNAL_STORAGE` on older versions. Partial access is reported as `limited`. | Partial access is reported as `limited`.                                             | Always `unavailable`.                               |
| `REMINDERS`       | Always `unavailable`.                                                                                                                                                     | Covers the reminders authorization.                                                  | Always `unavailable`.                               |

## Requesting background location

The `LOCATION_ALWAYS` permission should only be requested after the `LOCATION` permission has been granted:

1. Request the `LOCATION` permission and explain why you need location access.
1. Once granted, request the `LOCATION_ALWAYS` permission.

On Android 11 and later, the system does not display a prompt for background location. Instead, the user is taken to the system settings to select the "Allow all the time" option. If the `LOCATION` permission has not been granted yet, the request is denied immediately by the system.

On iOS, the system only displays the upgrade prompt from when-in-use to always access once. If the user has already made a decision, the current state is returned.

## Recovering from denied permissions

If a permission is in the `denied` state, it can no longer be requested from within the app. In this case, you can guide the user to the app settings using the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugin:

```
import { SettingsLauncher } from '@capawesome/capacitor-settings-launcher';

const openAppSettings = async () => {
  await SettingsLauncher.openAppSettings();
};
```

## App Tracking Transparency

The App Tracking Transparency permission is deliberately not part of this plugin. Use the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugin instead.

## FAQ

### How is this plugin different from other similar plugins?

It brings many device permissions under one unified, fully typed API — Bluetooth, calendar, camera, contacts, location, background location, microphone, motion, notifications, photos and reminders — so you check and request them all in one place. The `check(...)` method never triggers a system prompt, and the plugin declares no permissions itself, so your app only ships the ones it actually uses. It is handcrafted with care, works across Android, iOS and the Web (partial), and stays current with the latest Capacitor version.

### Does the `check` method trigger a permission prompt?

No, the `check(...)` method never displays a permission prompt. It only reads the current states of the given permissions, so you can safely call it at any time, for example to build an onboarding or settings screen.

### Why does the `request` method reject with an error?

On Android, the corresponding permissions must be declared in the `AndroidManifest.xml` file of your app. On iOS, the corresponding usage description keys must be provided in the `Info.plist` file of your app. If a declaration is missing, the `request(...)` method rejects with a clear error message. See the [Installation](#installation) section for the required entries per permission.

### Do I need to declare all supported permissions in my app?

No, the plugin itself does not declare any permissions and does not require any Info.plist keys. Your app only declares exactly the permissions it actually uses. This way, your app does not request permissions it does not need.

### How do I request background location access?

Request the `LOCATION` permission first and, once it has been granted, request the `LOCATION_ALWAYS` permission. On Android 11 and later, the system does not display a prompt for background location; instead, the user is taken to the system settings to select the "Allow all the time" option. On iOS, the system only displays the upgrade prompt from when-in-use to always access once.

### What can I do if a permission is denied?

If a permission is in the `denied` state, it can no longer be requested from within the app. In this case, you can guide the user to the app settings using the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugin so they can grant the permission manually.

### Which permissions are supported on the web?

On the web, only the `NOTIFICATIONS` permission can be checked and requested. The `CAMERA`, `LOCATION` and `MICROPHONE` permissions support checking, while requesting returns the current state since browsers display the permission prompt when the corresponding web API is used for the first time. All other permissions are reported as `unavailable`. See the [Platform behavior](#platform-behavior) section for details.

## Related Plugins

- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the App Tracking Transparency permission on iOS.
- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens, for example to recover from denied permissions.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/permissions/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/permissions/LICENSE).

# Capacitor Phone Dialer Plugin

Capacitor plugin to open the native phone dialer prefilled with a phone number.

## Features

- 📞 **Dial**: Open the native phone dialer prefilled with a phone number.
- ✅ **Capability check**: Check whether the device is able to open the phone dialer.
- 🔒 **Privacy-friendly**: The user always reviews the number and places the call. The plugin never calls on its own.
- 🤝 **Compatibility**: Works alongside the [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Phone Dialer plugin is typically used whenever an app wants to offer a tap-to-call experience, for example:

- **Customer support**: Let users call your support hotline directly from a help or contact screen.
- **Business directories**: Let users call a listed business, restaurant, or practice with a single tap.
- **CRM and field service apps**: Let users call customers or leads from a detail view, with the number prefilled in the dialer.
- **Capability-aware UI**: Use the `canDial()` method to hide or disable call buttons on devices without telephony capability, such as Wi-Fi-only tablets.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-phone-dialer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-phone-dialer
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On Web, all methods reject as unimplemented. Use an `<a href="tel:...">` link on the web instead.

### Android

No additional configuration is required. The plugin declares the necessary `<queries>` element for the `tel` scheme in its `AndroidManifest.xml`, so the phone dialer can be detected on Android 11 (API level 30) and higher.

### iOS

To be able to detect whether the device can open the phone dialer, add the `tel` scheme to the `LSApplicationQueriesSchemes` array in your app's `Info.plist` file:

```
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>tel</string>
</array>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the device can open the phone dialer and how to open it with a prefilled number.

### Check whether the device can open the phone dialer

Use the `canDial()` method to check whether the device is able to open the phone dialer, for example to hide or disable call buttons. On devices without telephony capability (e.g. Wi-Fi-only tablets or iPod touch), it resolves with `false`. Only available on Android and iOS:

```
import { PhoneDialer } from '@capawesome/capacitor-phone-dialer';

const canDial = async () => {
  const { canDial } = await PhoneDialer.canDial();
  return canDial;
};
```

### Open the phone dialer with a prefilled number

Use the `dial(...)` method to open the native phone dialer prefilled with the given number. The user reviews the number and decides whether to place the call. Only available on Android and iOS:

```
import { PhoneDialer } from '@capawesome/capacitor-phone-dialer';

const dial = async () => {
  await PhoneDialer.dial({ number: '+41791234567' });
};
```

## API

- [`canDial()`](#candial)
- [`dial(...)`](#dial)
- [Interfaces](#interfaces)

### canDial()

```
canDial() => Promise<CanDialResult>
```

Check whether the device is able to open the phone dialer.

On devices without telephony capability (e.g. Wi-Fi-only tablets or iPod touch), this resolves with `canDial` set to `false`.

Only available on Android and iOS.

**Returns:** `Promise<CanDialResult>`

**Since:** 0.1.0

______________________________________________________________________

### dial(...)

```
dial(options: DialOptions) => Promise<void>
```

Open the native phone dialer prefilled with the given number.

The user reviews the number and decides whether to place the call. The plugin never places the call itself.

If the device is not able to open the phone dialer, the call rejects as unavailable.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `DialOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CanDialResult

| Prop          | Type      | Description                                          | Since |
| ------------- | --------- | ---------------------------------------------------- | ----- |
| **`canDial`** | `boolean` | Whether the device is able to open the phone dialer. | 0.1.0 |

#### DialOptions

| Prop         | Type     | Description                                                                                                                                                                   | Since |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`number`** | `string` | The phone number to prefill in the dialer. Only digits and the characters `+`, `*` and `#` are kept. All other characters (e.g. spaces or dashes) are removed before dialing. | 0.1.0 |

## Direct Calling

This plugin only **opens** the phone dialer prefilled with the number. It never places the call directly. This is a deliberate design decision:

- On **Android**, direct calling would require the `android.permission.CALL_PHONE` runtime permission and comes with additional Google Play policy requirements. The plugin uses `Intent.ACTION_DIAL`, which does not require any permission.
- On **iOS**, there is no public API to place a call without user confirmation. The plugin opens the `tel:` URL, which shows the system Call/Cancel confirmation.

## Number Sanitization

Before opening the dialer, the phone number is sanitized: all characters except digits and `+`, `*` and `#` are removed. If nothing remains after sanitization, the call rejects with an error.

## FAQ

### How is this plugin different from other similar plugins?

It opens the native phone dialer prefilled with a number on Android and iOS, and adds a `canDial()` capability check so you can hide or disable call buttons on devices without telephony, such as Wi-Fi-only tablets. It is privacy-friendly by design: the user always reviews the number and places the call, so on Android it needs no runtime permission by using `Intent.ACTION_DIAL`, and it sanitizes the number for you before dialing. The API is fully typed, supports both CocoaPods and Swift Package Manager on iOS, and is actively maintained against the latest Capacitor and OS versions.

### Can the plugin place a phone call directly without user confirmation?

No, this is a deliberate design decision. On Android, direct calling would require the `CALL_PHONE` runtime permission and comes with additional Google Play policy requirements, so the plugin uses `Intent.ACTION_DIAL` instead. On iOS, there is no public API to place a call without user confirmation. The plugin always opens the dialer prefilled with the number and the user decides whether to place the call.

### Does the plugin require any permissions?

No, the plugin does not require any runtime permissions. On Android, it uses `Intent.ACTION_DIAL`, which does not require any permission. On iOS, you only need to add the `tel` scheme to the `LSApplicationQueriesSchemes` array in your app's `Info.plist` file so that the `canDial()` method can detect whether the device can open the phone dialer (see [Installation](#installation)).

### Why does the `canDial` method return `false`?

The `canDial()` method resolves with `false` on devices without telephony capability, such as Wi-Fi-only tablets or iPod touch. On iOS, it also returns `false` if the `tel` scheme is missing from the `LSApplicationQueriesSchemes` array in your app's `Info.plist` file.

### What happens to spaces or dashes in the phone number?

Before opening the dialer, the phone number is sanitized: all characters except digits and `+`, `*` and `#` are kept, everything else (e.g. spaces or dashes) is removed. If nothing remains after sanitization, the call rejects with an error.

### Can I use this plugin on the Web?

No, the plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented. Use an `<a href="tel:...">` link on the web instead.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/): Read, write, or select device contacts, for example to look up a phone number before dialing.
- [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/): Open the native email composer.
- [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/phone-dialer/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/phone-dialer/LICENSE).

# Capacitor Photo Editor Plugin

Capacitor plugin that allows the user to edit a photo.

## Use Cases

The Photo Editor plugin is typically used whenever an app wants to hand a photo over to an installed photo editing app on Android, for example:

- **Photo touch-ups before upload**: Let users edit a photo (e.g. in Google Photos) before it is uploaded to your server.
- **Screenshot annotation**: Let users mark up a screenshot before attaching it to a bug report or support ticket.
- **Profile picture adjustments**: Let users fine-tune a selected photo before it is saved as their profile picture.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

| Android |
| ------- |
|         |

## Guides

- [How to Take and Edit Photos in a Capacitor App](https://capawesome.io/blog/how-to-take-and-edit-photos-in-a-capacitor-app/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-photo-editor` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-photo-editor
npx cap sync
```

### Android

You need to specify the directories that contain the photos you want to edit. To specify the directories, start by creating the file `file_paths.xml` in the `res/xml/` subdirectory of your project (see [Android docs](https://developer.android.com/training/secure-file-sharing/setup-sharing#DefineMetaData)).\
This is an example:

```
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="files" path="." />
    <cache-path name="cache" path="." />
    <external-files-path name="external-files" path="." />
    <external-cache-path name="external-cache" path="." />
    <external-path name="external" path="." />
</paths>
```

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to open a photo in an installed photo editing app.

### Edit a photo

Open a photo at a given path in an installed photo editing app (e.g. Google Photos). The user should overwrite the image when saving so that the path to the image is not lost. Only available on Android:

```
import { PhotoEditor } from '@capawesome/capacitor-photo-editor';

const editPhoto = async () => {
  await PhotoEditor.editPhoto({ path: 'data/image.png' });
};
```

## API

- [`editPhoto(...)`](#editphoto)
- [Interfaces](#interfaces)

### editPhoto(...)

```
editPhoto(options: EditPhotoOptions) => Promise<void>
```

Edit a photo at a given path.

**Attention**: A suitable photo editing app must be installed (e.g. Google Photos) and the user should overwrite the image when saving so that the path to the image is not lost.

Only available on Android.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `EditPhotoOptions` |

______________________________________________________________________

### Interfaces

#### EditPhotoOptions

| Prop       | Type     | Description                   |
| ---------- | -------- | ----------------------------- |
| **`path`** | `string` | The path of the file to edit. |

## FAQ

### Which platforms are supported?

The `editPhoto(...)` method is only available on Android. On iOS and the Web, there is no comparable way to hand a photo over to an installed editing app. For headless image transforms that work across platforms, take a look at the [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/) plugin.

### Why does nothing happen when I call the `editPhoto` method?

A suitable photo editing app (e.g. Google Photos) must be installed on the device. The plugin hands the photo over to that app instead of providing its own editing user interface.

### Why can I no longer find my photo after editing it?

The user should overwrite the image when saving in the editing app so that the path to the image is not lost. If the editing app saves the result as a new file, the original path no longer points to the edited version.

### Why do I need a `file_paths.xml` file on Android?

The plugin shares the photo with the editing app, so you need to specify the directories that contain the photos you want to edit. Create the file `file_paths.xml` in the `res/xml/` subdirectory of your project as shown in the [Installation](#installation) section and the [Android docs](https://developer.android.com/training/secure-file-sharing/setup-sharing#DefineMetaData).

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Exif](https://capawesome.io/docs/sdks/capacitor/exif/): Read, write and remove EXIF metadata from image files.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select the photo to edit from the gallery or file system.
- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/): Headless image transforms like crop, resize, rotate, flip and format conversion, including HEIC to JPEG.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-editor/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-editor/LICENSE).

## Credits

This plugin is based on the [Capacitor Photo Editor](https://github.com/capawesome-team/capacitor-photo-editor) plugin. Thanks to everyone who contributed to the project!

# Capacitor Photo Manipulator Plugin

Capacitor plugin for headless image transforms like crop, resize, rotate, flip and format conversion, including HEIC to JPEG.

## Features

- 🖼️ **Headless Transforms**: Crop, resize, rotate and flip images from code, without any UI.
- 🔄 **HEIC to JPEG**: Convert HEIC and AVIF photos to JPEG, PNG or WebP with the native platform decoders. No WASM blobs, no WebView memory spikes.
- 📐 **Upright Output**: The EXIF orientation is applied during decoding so the output is always upright.
- 🧠 **Memory Efficient**: Bounds-aware downsampled decoding, so full-resolution bitmaps are never loaded when resizing.
- 🕵️ **Privacy Friendly**: All metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding.
- 📂 **File Output**: Results are written to files, so even large images don't exhaust memory.
- ℹ️ **Image Info**: Read the dimensions and format of an image without decoding the pixel data.
- 🔒 **App Store safe**: Uses only official platform APIs.
- 🤝 **Compatibility**: Works alongside the [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/), [Exif](https://capawesome.io/docs/sdks/capacitor/exif/) and [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Photo Manipulator plugin is typically used whenever an app needs to process images from code, without any UI, for example:

- **HEIC to JPEG conversion**: Convert photos taken on an iPhone to JPEG before uploading them, so servers and browsers can display them.
- **Thumbnail generation**: Crop and resize images to small previews with memory-efficient downsampled decoding.
- **Upload size reduction**: Resize images and re-encode them with a lower `quality` before uploading them to a server.
- **Privacy-safe sharing**: Share images without metadata, since all metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding.
- **Orientation fixes**: Produce upright images, since the EXIF orientation is applied during decoding.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [How to Take and Edit Photos in a Capacitor App](https://capawesome.io/blog/how-to-take-and-edit-photos-in-a-capacitor-app/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-photo-manipulator` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-photo-manipulator
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxExifInterfaceVersion` version of `androidx.exifinterface:exifinterface` (default: `1.4.1`)

### iOS

On iOS, this plugin uses the [Image I/O](https://developer.apple.com/documentation/imageio) and [Core Graphics](https://developer.apple.com/documentation/coregraphics) frameworks. No additional configuration is required.

### Web

This plugin provides a partial web implementation based on the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API). HEIC and AVIF images can not be decoded by most browsers, which is exactly why the native implementations exist (see [Format Support](#format-support)).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to convert an image to another format, create a thumbnail, and read the dimensions and format of an image.

The transformed image is written to a new file in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the `rename(...)` method of the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin.

### Convert a HEIC image to JPEG

Use the `format` option of the `transform(...)` method to convert an image to another format, for example a HEIC photo taken on an iPhone to JPEG. The `quality` option controls the compression of the output file:

```
import { PhotoManipulator, ImageFormat } from '@capawesome/capacitor-photo-manipulator';

const convertHeicToJpeg = async () => {
  // Convert an HEIC photo (e.g. taken on an iPhone) to JPEG
  const { path } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.heic',
    format: ImageFormat.Jpeg,
    quality: 0.9,
  });
  return path;
};
```

### Create a thumbnail

Combine the `crop`, `resize`, `rotate` and flip options in a single call. The operations are always applied in the fixed order crop → resize → rotate → flip:

```
import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const createThumbnail = async () => {
  // Crop, resize, rotate and flip in one call
  const { path, width, height } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.jpeg',
    crop: { x: 100, y: 100, width: 1080, height: 1080 },
    resize: { width: 256 },
    rotate: 90,
    flipHorizontal: true,
  });
  return { path, width, height };
};
```

### Read the dimensions and format of an image

Use the `getInfo(...)` method to read the dimensions and format of an image without decoding the pixel data where possible:

```
import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const getInfo = async () => {
  const { width, height, format } = await PhotoManipulator.getInfo({
    path: 'file:///var/mobile/.../photo.heic',
  });
  return { width, height, format };
};
```

## API

- [`getInfo(...)`](#getinfo)
- [`transform(...)`](#transform)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getInfo(...)

```
getInfo(options: GetInfoOptions) => Promise<GetInfoResult>
```

Get the dimensions and format of an image without decoding the pixel data where possible.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `GetInfoOptions` |

**Returns:** `Promise<GetInfoResult>`

**Since:** 0.1.0

______________________________________________________________________

### transform(...)

```
transform(options: TransformOptions) => Promise<TransformResult>
```

Apply one or more transformations to an image and write the result to a new file.

The operations are always applied in the following fixed order: crop → resize → rotate → flip. Chain multiple calls if you need a different order.

The EXIF orientation of the source image is applied during decoding so that the output is always upright. All other metadata (e.g. EXIF, GPS) is stripped by re-encoding.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `TransformOptions` |

**Returns:** `Promise<TransformResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetInfoResult

| Prop         | Type     | Description                                                                    | Since                                                                                                                                                                                                                                      |
| ------------ | -------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`format`** | \`string | null\`                                                                         | The format of the image or `null` if the format could not be determined. The value is provided by the platform decoder and may differ slightly between platforms for the same file (e.g. `heic` on iOS and the web but `heif` on Android). |
| **`height`** | `number` | The height of the image in pixels after the EXIF orientation has been applied. | 0.1.0                                                                                                                                                                                                                                      |
| **`width`**  | `number` | The width of the image in pixels after the EXIF orientation has been applied.  | 0.1.0                                                                                                                                                                                                                                      |

#### GetInfoOptions

| Prop       | Type     | Description                                                                                                                                                                             | Since |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path of the image file. On Android and iOS, only local file paths and `file://` URIs are supported. On the web, any fetchable URL (e.g. `https://`, `blob:`, `data:`) is supported. | 0.1.0 |

#### TransformResult

| Prop         | Type     | Description                                                                                                                                                                                                                              | Since |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the transformed image in pixels.                                                                                                                                                                                           | 0.1.0 |
| **`path`**   | `string` | The path of the transformed image file. On Android and iOS, the file is stored in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it. On the web, the path is an object URL. | 0.1.0 |
| **`width`**  | `number` | The width of the transformed image in pixels.                                                                                                                                                                                            | 0.1.0 |

#### TransformOptions

| Prop                 | Type            | Description                                                                                                                                                                                          | Default            | Since |
| -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| **`crop`**           | `CropOptions`   | The region of the source image to crop to, in source pixels. The region must be within the bounds of the source image.                                                                               |                    | 0.1.0 |
| **`flipHorizontal`** | `boolean`       | Whether or not to flip the image horizontally.                                                                                                                                                       | `false`            | 0.1.0 |
| **`flipVertical`**   | `boolean`       | Whether or not to flip the image vertically.                                                                                                                                                         | `false`            | 0.1.0 |
| **`format`**         | `ImageFormat`   | The format of the output file. On iOS, [`ImageFormat.Webp`](#imageformat) is not supported and rejects with the `UNSUPPORTED_FORMAT` error code.                                                     | `ImageFormat.Jpeg` | 0.1.0 |
| **`path`**           | `string`        | The path of the image file to transform. On Android and iOS, only local file paths and `file://` URIs are supported. On the web, any fetchable URL (e.g. `https://`, `blob:`, `data:`) is supported. |                    | 0.1.0 |
| **`quality`**        | `number`        | The quality of the output file between `0` and `1`. Only applied when `format` is [`ImageFormat.Jpeg`](#imageformat) or [`ImageFormat.Webp`](#imageformat).                                          | `0.9`              | 0.1.0 |
| **`resize`**         | `ResizeOptions` | The target size to resize the image to, in pixels. If only one of `width` and `height` is provided, the aspect ratio is preserved. The resize is applied after the crop.                             |                    | 0.1.0 |
| **`rotate`**         | `number`        | The clockwise angle to rotate the image by, in degrees. Must be `90`, `180` or `270`.                                                                                                                | `0`                | 0.1.0 |

#### CropOptions

| Prop         | Type     | Description                                                                                          | Since |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the crop region in pixels.                                                             | 0.1.0 |
| **`width`**  | `number` | The width of the crop region in pixels.                                                              | 0.1.0 |
| **`x`**      | `number` | The horizontal offset of the crop region in pixels, measured from the left edge of the source image. | 0.1.0 |
| **`y`**      | `number` | The vertical offset of the crop region in pixels, measured from the top edge of the source image.    | 0.1.0 |

#### ResizeOptions

| Prop         | Type     | Description                                                                                                  | Since |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------ | ----- |
| **`height`** | `number` | The target height in pixels. If only one of `width` and `height` is provided, the aspect ratio is preserved. | 0.1.0 |
| **`width`**  | `number` | The target width in pixels. If only one of `width` and `height` is provided, the aspect ratio is preserved.  | 0.1.0 |

### Enums

#### ImageFormat

| Members    | Value    | Description                                             | Since |
| ---------- | -------- | ------------------------------------------------------- | ----- |
| **`Jpeg`** | `'JPEG'` | JPEG (`image/jpeg`).                                    | 0.1.0 |
| **`Png`**  | `'PNG'`  | PNG (`image/png`).                                      | 0.1.0 |
| **`Webp`** | `'WEBP'` | WebP (`image/webp`). Only available on Android and Web. | 0.1.0 |

## Format Support

The formats an image can be decoded from and encoded to depend on the platform:

### Input (Decode)

| Format    | Android          | iOS          | Web               |
| --------- | ---------------- | ------------ | ----------------- |
| JPEG      | ✅               | ✅           | ✅                |
| PNG       | ✅               | ✅           | ✅                |
| WebP      | ✅               | ✅           | ✅                |
| GIF       | ✅               | ✅           | ✅                |
| BMP       | ✅               | ✅           | ✅                |
| HEIC/HEIF | ✅ (Android 9+)  | ✅           | ❌                |
| AVIF      | ✅ (Android 12+) | ✅ (iOS 16+) | Browser-dependent |

### Output (Encode)

| Format | Android | iOS | Web               |
| ------ | ------- | --- | ----------------- |
| JPEG   | ✅      | ✅  | ✅                |
| PNG    | ✅      | ✅  | ✅                |
| WebP   | ✅      | ❌  | Browser-dependent |

If an image can not be decoded or encoded on the current platform, the call is rejected with the `UNSUPPORTED_FORMAT` error code so you can fall back gracefully.

## Memory

This plugin is designed to keep the memory footprint low, even for very large images:

- When a `resize` target is provided, the image is decoded downsampled (using `inSampleSize` on Android and `kCGImageSourceThumbnailMaxPixelSize` on iOS) so the full-resolution bitmap is never loaded into memory.
- Transforms are processed one at a time on a background queue.
- The result is written to a file instead of being returned as base64 data.

For the smallest possible memory footprint, always provide a `resize` target if you don't need the full resolution.

## Metadata

The EXIF orientation of the source image is applied during decoding so that the output is always upright. All other metadata (e.g. EXIF, GPS) is stripped by re-encoding. Use the [Exif](https://capawesome.io/docs/sdks/capacitor/exif/) plugin if you want to read the metadata of the source image and write it back to the transformed image.

## FAQ

### How is this plugin different from other similar plugins?

It performs headless image transforms — crop, resize, rotate, flip and format conversion, including HEIC and AVIF to JPEG, PNG or WebP — using the native platform decoders, with no UI and no WebView memory spikes. It decodes bounds-aware and downsampled so full-resolution bitmaps are never loaded when resizing, applies the EXIF orientation for always-upright output, writes results to files, and strips metadata on re-encode for privacy-safe sharing. It works on Android, iOS and the Web, uses only official platform APIs, and is fully typed and kept current with the latest Capacitor version.

### In which order are the transformations applied?

The operations are always applied in the following fixed order: crop → resize → rotate → flip. If you need a different order, chain multiple `transform(...)` calls, passing the output path of one call as the input path of the next.

### Why does the transformed image disappear after an app restart?

On Android and iOS, the transformed image is written to a new file in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the `rename(...)` method of the official [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin.

### Does the plugin preserve the EXIF metadata of the source image?

No, the EXIF orientation is applied during decoding so that the output is always upright, and all other metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding. This is privacy-friendly by default. If you want to keep the metadata, use the [Exif](https://capawesome.io/docs/sdks/capacitor/exif/) plugin to read it from the source image and write it back to the transformed image.

### Why does converting to WebP fail on iOS?

On iOS, `ImageFormat.Webp` is not supported as an output format and the call rejects with the `UNSUPPORTED_FORMAT` error code. WebP output is only available on Android and the Web. Use `ImageFormat.Jpeg` or `ImageFormat.Png` as a cross-platform alternative.

### Why can't I convert HEIC or AVIF images on the Web?

The web implementation is based on the Canvas API, and most browsers cannot decode HEIC and AVIF images. This is exactly why the native implementations exist: on Android (9+ for HEIC/HEIF, 12+ for AVIF) and iOS (16+ for AVIF), the plugin uses the native platform decoders. See the [Format Support](#format-support) section for the complete overview.

### How does the plugin handle very large images?

The plugin is designed to keep the memory footprint low. When a `resize` target is provided, the image is decoded downsampled so the full-resolution bitmap is never loaded into memory, transforms are processed one at a time on a background queue, and the result is written to a file instead of being returned as base64 data. For the smallest possible memory footprint, always provide a `resize` target if you don't need the full resolution.

## Related Plugins

- [Exif](https://capawesome.io/docs/sdks/capacitor/exif/): Read, write and remove EXIF metadata from image files.
- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress files with support for image formats like PNG, JPEG, and WebP.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select the images to transform from the gallery or file system.
- [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/): Let the user edit a photo in an installed photo editing app.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-manipulator/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-manipulator/LICENSE).

# Capacitor PixLive Plugin

Unofficial Capacitor plugin for [PixLive SDK](https://www.vidinoti.com/) by Vidinoti.

## Use Cases

The PixLive plugin is typically used to build augmented reality experiences with content managed in PixLive Maker, for example:

- **Interactive print media**: Bring magazines, flyers, or posters to life with AR content that appears when a context is recognized by the AR camera.
- **Guided tours**: Synchronize tours and contexts to guide visitors through museums, exhibitions, or cities.
- **Location-based experiences**: Trigger content or local notifications when the user approaches GPS points or beacons.
- **QR code interactions**: React to QR codes and barcodes scanned by the AR camera via the `codeRecognize` event.

## Installation

```
npm install @capawesome/capacitor-pixlive
npx cap sync
```

### Android

#### SDK Setup

Copy the `vdarsdk-release.aar` file into your app's `android/app/libs/` directory.

### iOS

Please note, that this plugin does not support SPM but only Cocoapods as iOS dependency manager.

#### SDK Setup

The PixLive iOS SDK (`VDARSDK.xcframework`) must be manually added by copying `VDARSDK.xcframework` into `ios/App/Frameworks/` in your Capacitor project.

## Configuration

Configure the plugin in your `capacitor.config.ts`:

```
const config: CapacitorConfig = {
  plugins: {
    Pixlive: {
      licenseKey: 'YOUR_LICENSE_KEY',
      apiUrl: 'https://ar.vidinoti.com/api/api.php', // optional
      sdkUrl: 'https://sdk.vidinoti.com', // optional
    },
  },
};
```

| Prop             | Type     | Description                      | Default                               |
| ---------------- | -------- | -------------------------------- | ------------------------------------- |
| **`licenseKey`** | `string` | The PixLive Maker license key.   |                                       |
| **`apiUrl`**     | `string` | The PixLive Maker API endpoint.  | `https://ar.vidinoti.com/api/api.php` |
| **`sdkUrl`**     | `string` | The PixLive SDK resource server. | `https://sdk.vidinoti.com`            |

## Usage

The following examples show how to synchronize content from PixLive Maker and display the AR view.

### Synchronize content from PixLive Maker

Sync AR content from PixLive Maker filtered by tags so that it is available on the device. Only available on Android and iOS:

```
import { Pixlive } from '@capawesome/capacitor-pixlive';

const synchronize = async () => {
  await Pixlive.synchronize({ tags: [['my-tag']] });
};
```

### Display the AR view

Create the native AR camera view at the specified screen coordinates. Only available on Android and iOS:

```
import { Pixlive } from '@capawesome/capacitor-pixlive';

const createARView = async () => {
  await Pixlive.createARView({ x: 0, y: 0, width: 300, height: 400 });
};
```

## API

- [`initialize()`](#initialize)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions(...)`](#requestpermissions)
- [`synchronize(...)`](#synchronize)
- [`synchronizeWithToursAndContexts(...)`](#synchronizewithtoursandcontexts)
- [`updateTagMapping(...)`](#updatetagmapping)
- [`enableContextsWithTags(...)`](#enablecontextswithtags)
- [`getContexts()`](#getcontexts)
- [`getContext(...)`](#getcontext)
- [`activateContext(...)`](#activatecontext)
- [`stopContext()`](#stopcontext)
- [`getNearbyGPSPoints(...)`](#getnearbygpspoints)
- [`getGPSPointsInBoundingBox(...)`](#getgpspointsinboundingbox)
- [`getNearbyBeacons()`](#getnearbybeacons)
- [`startNearbyGPSDetection()`](#startnearbygpsdetection)
- [`stopNearbyGPSDetection()`](#stopnearbygpsdetection)
- [`startGPSNotifications()`](#startgpsnotifications)
- [`stopGPSNotifications()`](#stopgpsnotifications)
- [`setNotificationsSupport(...)`](#setnotificationssupport)
- [`setInterfaceLanguage(...)`](#setinterfacelanguage)
- [`createARView(...)`](#createarview)
- [`destroyARView()`](#destroyarview)
- [`resizeARView(...)`](#resizearview)
- [`setARViewTouchEnabled(...)`](#setarviewtouchenabled)
- [`setARViewTouchHole(...)`](#setarviewtouchhole)
- [`getVersion()`](#getversion)
- [`addListener('codeRecognize', ...)`](#addlistenercoderecognize-)
- [`addListener('enterContext', ...)`](#addlistenerentercontext-)
- [`addListener('exitContext', ...)`](#addlistenerexitcontext-)
- [`addListener('presentAnnotations', ...)`](#addlistenerpresentannotations-)
- [`addListener('hideAnnotations', ...)`](#addlistenerhideannotations-)
- [`addListener('eventFromContent', ...)`](#addlistenereventfromcontent-)
- [`addListener('syncProgress', ...)`](#addlistenersyncprogress-)
- [`addListener('requireSync', ...)`](#addlistenerrequiresync-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### initialize()

```
initialize() => Promise<void>
```

Initialize the PixLive SDK.

This must be called before any other method.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the status of permissions.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: PixlivePluginPermission | undefined) => Promise<PermissionStatus>
```

Request permissions.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `PixlivePluginPermission` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### synchronize(...)

```
synchronize(options: SynchronizeOptions) => Promise<void>
```

Sync content from PixLive Maker filtered by tags.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SynchronizeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### synchronizeWithToursAndContexts(...)

```
synchronizeWithToursAndContexts(options: SynchronizeWithToursAndContextsOptions) => Promise<void>
```

Sync content filtered by tags, tour IDs, and context IDs.

Only available on Android and iOS.

| Param         | Type                                     |
| ------------- | ---------------------------------------- |
| **`options`** | `SynchronizeWithToursAndContextsOptions` |

**Since:** 0.0.1

______________________________________________________________________

### updateTagMapping(...)

```
updateTagMapping(options: UpdateTagMappingOptions) => Promise<void>
```

Update tag-to-context mappings for language filtering.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `UpdateTagMappingOptions` |

**Since:** 0.0.1

______________________________________________________________________

### enableContextsWithTags(...)

```
enableContextsWithTags(options: EnableContextsWithTagsOptions) => Promise<void>
```

Enable only contexts matching specific tags.

Only available on Android and iOS.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `EnableContextsWithTagsOptions` |

**Since:** 0.0.1

______________________________________________________________________

### getContexts()

```
getContexts() => Promise<GetContextsResult>
```

Get all synchronized contexts.

Only available on Android and iOS.

**Returns:** `Promise<GetContextsResult>`

**Since:** 0.0.1

______________________________________________________________________

### getContext(...)

```
getContext(options: GetContextOptions) => Promise<GetContextResult>
```

Get a single context by ID.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `GetContextOptions` |

**Returns:** `Promise<GetContextResult>`

**Since:** 0.0.1

______________________________________________________________________

### activateContext(...)

```
activateContext(options: ActivateContextOptions) => Promise<void>
```

Programmatically trigger/activate a context.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `ActivateContextOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopContext()

```
stopContext() => Promise<void>
```

Stop the currently playing/active context.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### getNearbyGPSPoints(...)

```
getNearbyGPSPoints(options: GetNearbyGPSPointsOptions) => Promise<GetNearbyGPSPointsResult>
```

Get GPS points near a given location, sorted by distance.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `GetNearbyGPSPointsOptions` |

**Returns:** `Promise<GetNearbyGPSPointsResult>`

**Since:** 0.0.1

______________________________________________________________________

### getGPSPointsInBoundingBox(...)

```
getGPSPointsInBoundingBox(options: GetGPSPointsInBoundingBoxOptions) => Promise<GetGPSPointsInBoundingBoxResult>
```

Get all GPS points within a geographic bounding box.

Only available on Android and iOS.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `GetGPSPointsInBoundingBoxOptions` |

**Returns:** `Promise<GetGPSPointsInBoundingBoxResult>`

**Since:** 0.0.1

______________________________________________________________________

### getNearbyBeacons()

```
getNearbyBeacons() => Promise<GetNearbyBeaconsResult>
```

Get contexts associated with nearby detected beacons.

Only available on Android and iOS.

**Returns:** `Promise<GetNearbyBeaconsResult>`

**Since:** 0.0.1

______________________________________________________________________

### startNearbyGPSDetection()

```
startNearbyGPSDetection() => Promise<void>
```

Start background GPS proximity detection.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### stopNearbyGPSDetection()

```
stopNearbyGPSDetection() => Promise<void>
```

Stop background GPS proximity detection.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### startGPSNotifications()

```
startGPSNotifications() => Promise<void>
```

Enable GPS-triggered local notifications.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### stopGPSNotifications()

```
stopGPSNotifications() => Promise<void>
```

Disable GPS-triggered local notifications.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### setNotificationsSupport(...)

```
setNotificationsSupport(options: SetNotificationsSupportOptions) => Promise<void>
```

Enable or disable notification support.

Only available on Android and iOS.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SetNotificationsSupportOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setInterfaceLanguage(...)

```
setInterfaceLanguage(options: SetInterfaceLanguageOptions) => Promise<void>
```

Set the language for SDK UI elements.

Only available on Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `SetInterfaceLanguageOptions` |

**Since:** 0.0.1

______________________________________________________________________

### createARView(...)

```
createARView(options: CreateARViewOptions) => Promise<void>
```

Create the native AR camera view at specified screen coordinates.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `CreateARViewOptions` |

**Since:** 0.0.1

______________________________________________________________________

### destroyARView()

```
destroyARView() => Promise<void>
```

Destroy the AR camera view.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### resizeARView(...)

```
resizeARView(options: ResizeARViewOptions) => Promise<void>
```

Resize the AR view.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ResizeARViewOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setARViewTouchEnabled(...)

```
setARViewTouchEnabled(options: SetARViewTouchEnabledOptions) => Promise<void>
```

Enable or disable touch event interception on the AR view.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SetARViewTouchEnabledOptions` |

**Since:** 0.0.1

______________________________________________________________________

### setARViewTouchHole(...)

```
setARViewTouchHole(options: SetARViewTouchHoleOptions) => Promise<void>
```

Define a rectangular region where touches pass through the AR view to the web layer.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SetARViewTouchHoleOptions` |

**Since:** 0.0.1

______________________________________________________________________

### getVersion()

```
getVersion() => Promise<GetVersionResult>
```

Get the version of the sdk.

**Returns:** `Promise<GetVersionResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('codeRecognize', ...)

```
addListener(eventName: 'codeRecognize', listenerFunc: (event: CodeRecognizeEvent) => void) => Promise<PluginListenerHandle>
```

Called when a QR code or barcode is scanned by the AR camera.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'codeRecognize'`                     |
| **`listenerFunc`** | `(event: CodeRecognizeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('enterContext', ...)

```
addListener(eventName: 'enterContext', listenerFunc: (event: EnterContextEvent) => void) => Promise<PluginListenerHandle>
```

Called when an AR context is detected/entered.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'enterContext'`                     |
| **`listenerFunc`** | `(event: EnterContextEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('exitContext', ...)

```
addListener(eventName: 'exitContext', listenerFunc: (event: ExitContextEvent) => void) => Promise<PluginListenerHandle>
```

Called when an AR context is lost/exited.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'exitContext'`                     |
| **`listenerFunc`** | `(event: ExitContextEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('presentAnnotations', ...)

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

Called when AR content/annotations become visible on screen.

| Param              | Type                   |
| ------------------ | ---------------------- |
| **`eventName`**    | `'presentAnnotations'` |
| **`listenerFunc`** | `() => void`           |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('hideAnnotations', ...)

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

Called when AR content/annotations are hidden.

| Param              | Type                |
| ------------------ | ------------------- |
| **`eventName`**    | `'hideAnnotations'` |
| **`listenerFunc`** | `() => void`        |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('eventFromContent', ...)

```
addListener(eventName: 'eventFromContent', listenerFunc: (event: EventFromContentEvent) => void) => Promise<PluginListenerHandle>
```

Called when AR content dispatches a custom event.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'eventFromContent'`                     |
| **`listenerFunc`** | `(event: EventFromContentEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('syncProgress', ...)

```
addListener(eventName: 'syncProgress', listenerFunc: (event: SyncProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called during synchronization with progress updates.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'syncProgress'`                     |
| **`listenerFunc`** | `(event: SyncProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('requireSync', ...)

```
addListener(eventName: 'requireSync', listenerFunc: (event: RequireSyncEvent) => void) => Promise<PluginListenerHandle>
```

Called when the SDK requires synchronization with specific tags.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'requireSync'`                     |
| **`listenerFunc`** | `(event: RequireSyncEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop                   | Type              | Description                                                                      | Since |
| ---------------------- | ----------------- | -------------------------------------------------------------------------------- | ----- |
| **`bluetooth`**        | `PermissionState` | Permission state of the Bluetooth permission. Only available on iOS.             | 0.0.1 |
| **`bluetoothConnect`** | `PermissionState` | Permission state of the Bluetooth Connect permission. Only available on Android. | 0.0.1 |
| **`bluetoothScan`**    | `PermissionState` | Permission state of the Bluetooth Scan permission. Only available on Android.    | 0.0.1 |
| **`camera`**           | `PermissionState` | Permission state of the Camera permission.                                       | 0.0.1 |
| **`location`**         | `PermissionState` | Permission state of the Location permission. Only available on Android and iOS.  | 0.0.1 |
| **`notifications`**    | `PermissionState` | Permission state of the Notifications permission.                                | 0.0.1 |

#### PixlivePluginPermission

| Prop              | Type                      | Description                 | Since |
| ----------------- | ------------------------- | --------------------------- | ----- |
| **`permissions`** | `PixlivePermissionType[]` | The permissions to request. | 0.0.1 |

#### SynchronizeOptions

| Prop       | Type         | Description                    | Since |
| ---------- | ------------ | ------------------------------ | ----- |
| **`tags`** | `string[][]` | The tags to filter content by. | 0.0.1 |

#### SynchronizeWithToursAndContextsOptions

| Prop             | Type         | Description                    | Since |
| ---------------- | ------------ | ------------------------------ | ----- |
| **`tags`**       | `string[][]` | The tags to filter content by. | 0.0.1 |
| **`tourIds`**    | `number[]`   | The tour IDs to sync.          | 0.0.1 |
| **`contextIds`** | `string[]`   | The context IDs to sync.       | 0.0.1 |

#### UpdateTagMappingOptions

| Prop       | Type       | Description      | Since |
| ---------- | ---------- | ---------------- | ----- |
| **`tags`** | `string[]` | The tags to map. | 0.0.1 |

#### EnableContextsWithTagsOptions

| Prop       | Type       | Description                      | Since |
| ---------- | ---------- | -------------------------------- | ----- |
| **`tags`** | `string[]` | The tags to enable contexts for. | 0.0.1 |

#### GetContextsResult

| Prop           | Type        | Description                        | Since |
| -------------- | ----------- | ---------------------------------- | ----- |
| **`contexts`** | `Context[]` | The list of synchronized contexts. | 0.0.1 |

#### Context

| Prop                      | Type       | Description                              | Since                                 |
| ------------------------- | ---------- | ---------------------------------------- | ------------------------------------- |
| **`contextId`**           | `string`   | The unique identifier of the context.    | 0.0.1                                 |
| **`name`**                | `string`   | The name of the context.                 | 0.0.1                                 |
| **`description`**         | \`string   | null\`                                   | The description of the context.       |
| **`lastUpdate`**          | `string`   | The last update timestamp.               | 0.0.1                                 |
| **`imageThumbnailURL`**   | \`string   | null\`                                   | The URL of the thumbnail image.       |
| **`imageHiResURL`**       | \`string   | null\`                                   | The URL of the high-resolution image. |
| **`notificationTitle`**   | \`string   | null\`                                   | The notification title.               |
| **`notificationMessage`** | \`string   | null\`                                   | The notification message.             |
| **`tags`**                | `string[]` | The tags associated with the context.    | 0.0.1                                 |
| **`languages`**           | `string[]` | The languages provided for this context. | 0.1.3                                 |

#### GetContextResult

| Prop          | Type      | Description  | Since |
| ------------- | --------- | ------------ | ----- |
| **`context`** | `Context` | The context. | 0.0.1 |

#### GetContextOptions

| Prop            | Type     | Description                        | Since |
| --------------- | -------- | ---------------------------------- | ----- |
| **`contextId`** | `string` | The ID of the context to retrieve. | 0.0.1 |

#### ActivateContextOptions

| Prop            | Type     | Description                        | Since |
| --------------- | -------- | ---------------------------------- | ----- |
| **`contextId`** | `string` | The ID of the context to activate. | 0.0.1 |

#### GetNearbyGPSPointsResult

| Prop         | Type         | Description                               | Since |
| ------------ | ------------ | ----------------------------------------- | ----- |
| **`points`** | `GPSPoint[]` | The nearby GPS points sorted by distance. | 0.0.1 |

#### GPSPoint

| Prop                              | Type     | Description                                       | Since                           |
| --------------------------------- | -------- | ------------------------------------------------- | ------------------------------- |
| **`contextId`**                   | `string` | The ID of the associated context.                 | 0.0.1                           |
| **`category`**                    | `string` | The category of the GPS point.                    | 0.0.1                           |
| **`label`**                       | `string` | The label of the GPS point.                       | 0.0.1                           |
| **`latitude`**                    | `number` | The latitude of the GPS point.                    | 0.0.1                           |
| **`longitude`**                   | `number` | The longitude of the GPS point.                   | 0.0.1                           |
| **`detectionRadius`**             | \`number | null\`                                            | The detection radius in meters. |
| **`distanceFromCurrentPosition`** | `number` | The distance from the current position in meters. | 0.0.1                           |

#### GetNearbyGPSPointsOptions

| Prop            | Type     | Description                              | Since |
| --------------- | -------- | ---------------------------------------- | ----- |
| **`latitude`**  | `number` | The latitude of the reference location.  | 0.0.1 |
| **`longitude`** | `number` | The longitude of the reference location. | 0.0.1 |

#### GetGPSPointsInBoundingBoxResult

| Prop         | Type         | Description                             | Since |
| ------------ | ------------ | --------------------------------------- | ----- |
| **`points`** | `GPSPoint[]` | The GPS points within the bounding box. | 0.0.1 |

#### GetGPSPointsInBoundingBoxOptions

| Prop               | Type     | Description                                | Since |
| ------------------ | -------- | ------------------------------------------ | ----- |
| **`minLatitude`**  | `number` | The minimum latitude of the bounding box.  | 0.0.1 |
| **`minLongitude`** | `number` | The minimum longitude of the bounding box. | 0.0.1 |
| **`maxLatitude`**  | `number` | The maximum latitude of the bounding box.  | 0.0.1 |
| **`maxLongitude`** | `number` | The maximum longitude of the bounding box. | 0.0.1 |

#### GetNearbyBeaconsResult

| Prop           | Type        | Description                                  | Since |
| -------------- | ----------- | -------------------------------------------- | ----- |
| **`contexts`** | `Context[]` | The contexts associated with nearby beacons. | 0.0.1 |

#### SetNotificationsSupportOptions

| Prop          | Type      | Description                                      | Since |
| ------------- | --------- | ------------------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether notifications support should be enabled. | 0.0.1 |

#### SetInterfaceLanguageOptions

| Prop           | Type     | Description               | Since |
| -------------- | -------- | ------------------------- | ----- |
| **`language`** | `string` | The language code to set. | 0.0.1 |

#### CreateARViewOptions

| Prop         | Type     | Description                    | Since |
| ------------ | -------- | ------------------------------ | ----- |
| **`x`**      | `number` | The x position of the AR view. | 0.0.1 |
| **`y`**      | `number` | The y position of the AR view. | 0.0.1 |
| **`width`**  | `number` | The width of the AR view.      | 0.0.1 |
| **`height`** | `number` | The height of the AR view.     | 0.0.1 |

#### ResizeARViewOptions

| Prop         | Type     | Description                        | Since |
| ------------ | -------- | ---------------------------------- | ----- |
| **`x`**      | `number` | The new x position of the AR view. | 0.0.1 |
| **`y`**      | `number` | The new y position of the AR view. | 0.0.1 |
| **`width`**  | `number` | The new width of the AR view.      | 0.0.1 |
| **`height`** | `number` | The new height of the AR view.     | 0.0.1 |

#### SetARViewTouchEnabledOptions

| Prop          | Type      | Description                                                | Since |
| ------------- | --------- | ---------------------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether touch events should be intercepted by the AR view. | 0.0.1 |

#### SetARViewTouchHoleOptions

| Prop         | Type     | Description                                     | Since |
| ------------ | -------- | ----------------------------------------------- | ----- |
| **`top`**    | `number` | The top coordinate of the touch hole region.    | 0.0.1 |
| **`bottom`** | `number` | The bottom coordinate of the touch hole region. | 0.0.1 |
| **`left`**   | `number` | The left coordinate of the touch hole region.   | 0.0.1 |
| **`right`**  | `number` | The right coordinate of the touch hole region.  | 0.0.1 |

#### GetVersionResult

| Prop          | Type     | Description             | Since |
| ------------- | -------- | ----------------------- | ----- |
| **`version`** | `string` | The version of the sdk. | 0.0.1 |

#### PluginListenerHandle

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

#### CodeRecognizeEvent

| Prop       | Type     | Description                   | Since |
| ---------- | -------- | ----------------------------- | ----- |
| **`code`** | `string` | The scanned code value.       | 0.0.1 |
| **`type`** | `string` | The type of the scanned code. | 0.0.1 |

#### EnterContextEvent

| Prop            | Type     | Description                    | Since |
| --------------- | -------- | ------------------------------ | ----- |
| **`contextId`** | `string` | The ID of the entered context. | 0.0.1 |

#### ExitContextEvent

| Prop            | Type     | Description                   | Since |
| --------------- | -------- | ----------------------------- | ----- |
| **`contextId`** | `string` | The ID of the exited context. | 0.0.1 |

#### EventFromContentEvent

| Prop         | Type     | Description                         | Since |
| ------------ | -------- | ----------------------------------- | ----- |
| **`name`**   | `string` | The name of the custom event.       | 0.0.1 |
| **`params`** | `string` | The parameters of the custom event. | 0.0.1 |

#### SyncProgressEvent

| Prop           | Type     | Description                                  | Since |
| -------------- | -------- | -------------------------------------------- | ----- |
| **`progress`** | `number` | The sync progress value between 0.0 and 1.0. | 0.0.1 |

#### RequireSyncEvent

| Prop       | Type       | Description                            | Since |
| ---------- | ---------- | -------------------------------------- | ----- |
| **`tags`** | `string[]` | The tags that require synchronization. | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### PixlivePermissionType

`'bluetooth' | 'bluetoothConnect' | 'bluetoothScan' | 'camera' | 'location' | 'notifications'`

## FAQ

### Which method do I have to call first?

The `initialize()` method must be called before any other method of the plugin. It initializes the PixLive SDK using the license key from your Capacitor configuration file (see [Configuration](#configuration)).

### How do I set up the PixLive SDK in my project?

The PixLive SDK itself is not bundled with the plugin. On Android, copy the `vdarsdk-release.aar` file into your app's `android/app/libs/` directory. On iOS, copy `VDARSDK.xcframework` into `ios/App/Frameworks/` in your Capacitor project. See the [Installation](#installation) section for details.

### Does this plugin support Swift Package Manager?

No, this plugin only supports CocoaPods as the iOS dependency manager. Swift Package Manager is not supported.

### Does this plugin work on the Web?

No, the plugin methods are only available on Android and iOS since they rely on the native PixLive SDK.

### Which permissions does the plugin handle?

The plugin can check and request the camera, location, notifications, and Bluetooth permissions via the `checkPermissions()` and `requestPermissions(...)` methods. The Bluetooth permission is exposed as `bluetooth` on iOS and as `bluetoothConnect` and `bluetoothScan` on Android.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit.
- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with Bluetooth Low Energy devices such as beacons.
- [Geocoder](https://capawesome.io/docs/sdks/capacitor/geocoder/): Handle geocoding and reverse geocoding.

# Capacitor PostHog Plugin

Unofficial Capacitor plugin for [PostHog](https://posthog.com/).[1](#fn:1)

## Use Cases

The PostHog plugin is typically used to understand how users interact with an app, for example:

- **Product analytics**: Capture custom events and screen views to analyze how users move through your app.
- **User identification**: Identify users with a distinct ID, assign aliases, and associate their events with groups.
- **Feature flags**: Roll out features gradually by checking feature flags and their payloads at runtime.
- **Session replay**: Record user sessions to understand usage patterns and debug issues.
- **Error tracking**: Capture exceptions manually or automatically to monitor the stability of your app.

## Compatibility

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

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-posthog` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-posthog posthog-js
npx cap sync
```

### Android

#### 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:

- `$androidxCoreKtxVersion` version of `androidx.core:core-ktx` (default: `1.13.1`)
- `$posthogVersion` version of `com.posthog:posthog-android` (default: `3.27.2`)

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

## Configuration

| Prop                                    | Type                   | Description                                                                               | Default                      | Since |
| --------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | ---------------------------- | ----- |
| **`apiKey`**                            | `string`               | The API key of your PostHog project.                                                      |                              | 7.1.0 |
| **`apiHost`**                           | `string`               | The API host of your PostHog instance or reverse proxy.                                   | `'https://us.i.posthog.com'` | 8.3.0 |
| **`host`**                              | `string`               | The API host of your PostHog instance. Deprecated alias for `apiHost`.                    | `'https://us.i.posthog.com'` | 7.1.0 |
| **`uiHost`**                            | `string`               | The PostHog UI host used when `apiHost` points to a reverse proxy. Only available on Web. |                              | 8.3.0 |
| **`enableSessionReplay`**               | `boolean`              | Whether to enable session recording automatically.                                        | `false`                      | 7.3.0 |
| **`sessionReplayConfig`**               | `SessionReplayOptions` | Session recording configuration options.                                                  |                              | 7.3.0 |
| **`captureApplicationLifecycleEvents`** | `boolean`              | Whether to capture application lifecycle events.                                          | `true`                       | 8.3.0 |
| **`autoCaptureExceptions`**             | `boolean`              | Whether to automatically capture unhandled exceptions.                                    | `false`                      | 8.5.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "Posthog": {
      "apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      "apiHost": 'https://eu.i.posthog.com',
      "host": 'https://eu.i.posthog.com',
      "uiHost": 'https://eu.posthog.com',
      "enableSessionReplay": undefined,
      "sessionReplayConfig": undefined,
      "captureApplicationLifecycleEvents": undefined,
      "autoCaptureExceptions": undefined
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-posthog" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Posthog: {
      apiKey: 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      apiHost: 'https://eu.i.posthog.com',
      host: 'https://eu.i.posthog.com',
      uiHost: 'https://eu.posthog.com',
      enableSessionReplay: undefined,
      sessionReplayConfig: undefined,
      captureApplicationLifecycleEvents: undefined,
      autoCaptureExceptions: undefined,
    },
  },
};

export default config;
```

## Usage

The following examples show how to set up the SDK, capture events, track screen views, identify users, associate users with a group, manage super properties, reset the user, and flush queued events.

### Set up the SDK

Call `setup(...)` before any other method. Alternatively, on Android and iOS, you can configure the plugin in your Capacitor configuration file (see [Configuration](#configuration)); in that case, you must not call this method:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const setup = async () => {
  await Posthog.setup({
    apiKey: 'YOUR_API_KEY',
    apiHost: 'https://eu.i.posthog.com',
  });
};
```

### Capture events

Capture a custom event with optional properties:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const capture = async () => {
  await Posthog.capture({
    event: 'event',
    properties: {
      key: 'value',
    },
  });
};
```

### Track screen views

Send a screen event with the title of the screen. Only available on Android and iOS:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const screen = async () => {
  await Posthog.screen({
    screenTitle: 'screen',
    properties: {
      key: 'value',
    },
  });
};
```

### Identify users

Identify the current user with a distinct ID and set person properties. You can also assign another distinct ID to the current user using `alias(...)`:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const identify = async () => {
  await Posthog.identify({
    distinctId: 'distinct-id',
    userProperties: {
      key: 'value',
    },
  });
};

const alias = async () => {
  await Posthog.alias({
    alias: 'new-distinct-id',
  });
};
```

### Associate users with a group

Associate the events of the current user with a group, for example a company or a team:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const group = async () => {
  await Posthog.group({
    type: 'group',
    key: 'key',
    groupProperties: {
      key: 'value',
    },
  });
};
```

### Manage super properties

Register a super property that is sent with every event, and unregister it when it is no longer needed:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const register = async () => {
  await Posthog.register({
    key: 'super-property',
    value: 'super-value',
  });
};

const unregister = async () => {
  await Posthog.unregister({
    key: 'super-property',
  });
};
```

### Reset the user

Reset the current user's ID and anonymous ID, for example after a logout:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const reset = async () => {
  await Posthog.reset();
};
```

### Flush queued events

Manually flush all events in the queue. Only available on Android and iOS:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const flush = async () => {
  await Posthog.flush();
};
```

## API

- [`alias(...)`](#alias)
- [`capture(...)`](#capture)
- [`captureException(...)`](#captureexception)
- [`flush()`](#flush)
- [`getDistinctId()`](#getdistinctid)
- [`getFeatureFlag(...)`](#getfeatureflag)
- [`getFeatureFlagPayload(...)`](#getfeatureflagpayload)
- [`getSessionId()`](#getsessionid)
- [`group(...)`](#group)
- [`identify(...)`](#identify)
- [`isFeatureEnabled(...)`](#isfeatureenabled)
- [`isOptOut()`](#isoptout)
- [`optIn()`](#optin)
- [`optOut()`](#optout)
- [`register(...)`](#register)
- [`reloadFeatureFlags()`](#reloadfeatureflags)
- [`reset()`](#reset)
- [`screen(...)`](#screen)
- [`setPersonProperties(...)`](#setpersonproperties)
- [`setup(...)`](#setup)
- [`startSessionRecording()`](#startsessionrecording)
- [`stopSessionRecording()`](#stopsessionrecording)
- [`unregister(...)`](#unregister)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### alias(...)

```
alias(options: AliasOptions) => Promise<void>
```

Assign another distinct ID to the current user.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `AliasOptions` |

**Since:** 6.0.0

______________________________________________________________________

### capture(...)

```
capture(options: CaptureOptions) => Promise<void>
```

Capture an event.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `CaptureOptions` |

**Since:** 6.0.0

______________________________________________________________________

### captureException(...)

```
captureException(options: CaptureExceptionOptions) => Promise<void>
```

Capture an exception.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `CaptureExceptionOptions` |

**Since:** 8.5.0

______________________________________________________________________

### flush()

```
flush() => Promise<void>
```

Flush all events in the queue.

Only available on Android and iOS.

**Since:** 6.0.0

______________________________________________________________________

### getDistinctId()

```
getDistinctId() => Promise<GetDistinctIdResult>
```

Get the current distinct ID.

**Returns:** `Promise<GetDistinctIdResult>`

**Since:** 8.2.0

______________________________________________________________________

### getFeatureFlag(...)

```
getFeatureFlag(options: GetFeatureFlagOptions) => Promise<GetFeatureFlagResult>
```

Get the value of a feature flag.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetFeatureFlagOptions` |

**Returns:** `Promise<GetFeatureFlagResult>`

**Since:** 7.0.0

______________________________________________________________________

### getFeatureFlagPayload(...)

```
getFeatureFlagPayload(options: GetFeatureFlagPayloadOptions) => Promise<GetFeatureFlagPayloadResult>
```

Get the payload of a feature flag.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `GetFeatureFlagPayloadOptions` |

**Returns:** `Promise<GetFeatureFlagPayloadResult>`

**Since:** 7.1.0

______________________________________________________________________

### getSessionId()

```
getSessionId() => Promise<GetSessionIdResult>
```

Get the current session ID.

**Returns:** `Promise<GetSessionIdResult>`

**Since:** 8.6.0

______________________________________________________________________

### group(...)

```
group(options: GroupOptions) => Promise<void>
```

Associate the events for that user with a group.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `GroupOptions` |

**Since:** 6.0.0

______________________________________________________________________

### identify(...)

```
identify(options: IdentifyOptions) => Promise<void>
```

Identify the current user.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `IdentifyOptions` |

**Since:** 6.0.0

______________________________________________________________________

### isFeatureEnabled(...)

```
isFeatureEnabled(options: IsFeatureEnabledOptions) => Promise<IsFeatureEnabledResult>
```

Check if a feature flag is enabled.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `IsFeatureEnabledOptions` |

**Returns:** `Promise<IsFeatureEnabledResult>`

**Since:** 7.0.0

______________________________________________________________________

### isOptOut()

```
isOptOut() => Promise<IsOptOutResult>
```

Check if the user has opted out of capturing.

**Returns:** `Promise<IsOptOutResult>`

**Since:** 8.1.0

______________________________________________________________________

### optIn()

```
optIn() => Promise<void>
```

Opt in to event capturing.

**Since:** 8.1.0

______________________________________________________________________

### optOut()

```
optOut() => Promise<void>
```

Opt out of event capturing.

On Web with `cookielessMode: 'on_reject'`: switches to cookieless anonymous tracking. On iOS/Android: stops all event capturing entirely.

**Since:** 8.1.0

______________________________________________________________________

### register(...)

```
register(options: RegisterOptions) => Promise<void>
```

Register a new super property. This property will be sent with every event.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `RegisterOptions` |

**Since:** 6.0.0

______________________________________________________________________

### reloadFeatureFlags()

```
reloadFeatureFlags() => Promise<void>
```

Reload the feature flags.

**Since:** 7.0.0

______________________________________________________________________

### reset()

```
reset() => Promise<void>
```

Reset the current user's ID and anonymous ID.

**Since:** 6.0.0

______________________________________________________________________

### screen(...)

```
screen(options: ScreenOptions) => Promise<void>
```

Send a screen event.

Only available on Android and iOS.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `ScreenOptions` |

**Since:** 6.0.0

______________________________________________________________________

### setPersonProperties(...)

```
setPersonProperties(options: SetPersonPropertiesOptions) => Promise<void>
```

Set properties on the person associated with the current user.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `SetPersonPropertiesOptions` |

**Since:** 8.6.0

______________________________________________________________________

### setup(...)

```
setup(options: SetupOptions) => Promise<void>
```

Setup the PostHog SDK with the provided options.

**Attention**: This method should be called before any other method. Alternatively, on Android and iOS, you can configure this plugin in your Capacitor Configuration file. In this case, you must not call this method.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `SetupOptions` |

**Since:** 6.0.0

______________________________________________________________________

### startSessionRecording()

```
startSessionRecording() => Promise<void>
```

Start session recording.

**Since:** 7.3.0

______________________________________________________________________

### stopSessionRecording()

```
stopSessionRecording() => Promise<void>
```

Stop session recording.

**Since:** 7.3.0

______________________________________________________________________

### unregister(...)

```
unregister(options: UnregisterOptions) => Promise<void>
```

Remove a super property.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `UnregisterOptions` |

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### AliasOptions

| Prop        | Type     | Description                                        | Since |
| ----------- | -------- | -------------------------------------------------- | ----- |
| **`alias`** | `string` | The new distinct ID to assign to the current user. | 6.0.0 |

#### CaptureOptions

| Prop             | Type                  | Description                            | Since |
| ---------------- | --------------------- | -------------------------------------- | ----- |
| **`event`**      | `string`              | The name of the event to capture.      | 6.0.0 |
| **`properties`** | `Record<string, any>` | The properties to send with the event. | 6.0.0 |

#### CaptureExceptionOptions

| Prop             | Type                  | Description                                                                                                                | Default   | Since |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------- | ----- |
| **`message`**    | `string`              | The message of the exception.                                                                                              |           | 8.5.0 |
| **`name`**       | `string`              | The name of the exception. Used as the exception type for grouping.                                                        | `'Error'` | 8.5.0 |
| **`stacktrace`** | `StackFrame[]`        | The stack trace of the exception. Can be generated from an `Error` using [`stacktrace.js`](https://www.stacktracejs.com/). |           | 8.5.0 |
| **`properties`** | `Record<string, any>` | The properties to send with the exception.                                                                                 |           | 8.5.0 |

#### StackFrame

| Prop               | Type     | Description                        | Since |
| ------------------ | -------- | ---------------------------------- | ----- |
| **`functionName`** | `string` | The name of the function.          | 8.5.0 |
| **`fileName`**     | `string` | The name of the file.              | 8.5.0 |
| **`lineNumber`**   | `number` | The line number within the file.   | 8.5.0 |
| **`columnNumber`** | `number` | The column number within the file. | 8.5.0 |

#### GetDistinctIdResult

| Prop             | Type     | Description              | Since |
| ---------------- | -------- | ------------------------ | ----- |
| **`distinctId`** | `string` | The current distinct ID. | 8.2.0 |

#### GetFeatureFlagResult

| Prop        | Type     | Description | Since  |
| ----------- | -------- | ----------- | ------ |
| **`value`** | \`string | boolean     | null\` |

#### GetFeatureFlagOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`key`** | `string` | The key of the feature flag. | 7.0.0 |

#### GetFeatureFlagPayloadResult

| Prop        | Type       | Description                            | Since |
| ----------- | ---------- | -------------------------------------- | ----- |
| **`value`** | `JsonType` | The value of the feature flag payload. | 7.1.0 |

#### GetFeatureFlagPayloadOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`key`** | `string` | The key of the feature flag. | 7.1.0 |

#### GetSessionIdResult

| Prop            | Type     | Description | Since                                                                      |
| --------------- | -------- | ----------- | -------------------------------------------------------------------------- |
| **`sessionId`** | \`string | null\`      | The current session ID. If no session is active, the value will be `null`. |

#### GroupOptions

| Prop                  | Type                  | Description                                  | Since |
| --------------------- | --------------------- | -------------------------------------------- | ----- |
| **`type`**            | `string`              | The group type.                              | 6.0.0 |
| **`key`**             | `string`              | The group key.                               | 6.0.0 |
| **`groupProperties`** | `Record<string, any>` | The properties to send with the group event. | 6.0.0 |

#### IdentifyOptions

| Prop                 | Type                  | Description                   | Since |
| -------------------- | --------------------- | ----------------------------- | ----- |
| **`distinctId`**     | `string`              | The distinct ID of the user.  | 6.0.0 |
| **`userProperties`** | `Record<string, any>` | The person properties to set. | 6.0.0 |

#### IsFeatureEnabledResult

| Prop          | Type      | Description                                                                                         | Since |
| ------------- | --------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether the feature flag is enabled. If the feature flag does not exist, the value will be `false`. | 7.0.0 |

#### IsFeatureEnabledOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`key`** | `string` | The key of the feature flag. | 7.0.0 |

#### IsOptOutResult

| Prop           | Type      | Description                                  | Since |
| -------------- | --------- | -------------------------------------------- | ----- |
| **`optedOut`** | `boolean` | Whether the user has opted out of capturing. | 8.1.0 |

#### RegisterOptions

| Prop        | Type     | Description                      | Since |
| ----------- | -------- | -------------------------------- | ----- |
| **`key`**   | `string` | The name of the super property.  | 6.0.0 |
| **`value`** | `any`    | The value of the super property. | 6.0.0 |

#### ScreenOptions

| Prop              | Type                  | Description                                   | Since |
| ----------------- | --------------------- | --------------------------------------------- | ----- |
| **`screenTitle`** | `string`              | The name of the screen.                       | 6.0.0 |
| **`properties`**  | `Record<string, any>` | The properties to send with the screen event. | 6.0.0 |

#### SetPersonPropertiesOptions

| Prop                    | Type                  | Description                                                                      | Since |
| ----------------------- | --------------------- | -------------------------------------------------------------------------------- | ----- |
| **`properties`**        | `Record<string, any>` | The person properties to set.                                                    | 8.6.0 |
| **`setOnceProperties`** | `Record<string, any>` | The person properties to set only once. Existing values will not be overwritten. | 8.6.0 |

#### SetupOptions

| Prop                                    | Type                   | Description                                                                                                                                                                                                                                        | Default                                                                                                                                                                                                                                                                                      | Since |
| --------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`apiKey`**                            | `string`               | The API key of your PostHog project.                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                              | 6.0.0 |
| **`apiHost`**                           | `string`               | The API host of your PostHog instance or reverse proxy. If both `apiHost` and `host` are provided, `apiHost` takes precedence.                                                                                                                     | `'https://us.i.posthog.com'`                                                                                                                                                                                                                                                                 | 8.3.0 |
| **`host`**                              | `string`               | The API host of your PostHog instance. Deprecated alias for `apiHost`.                                                                                                                                                                             | `'https://us.i.posthog.com'`                                                                                                                                                                                                                                                                 | 6.0.0 |
| **`uiHost`**                            | `string`               | The PostHog UI host used when `apiHost` points to a reverse proxy. Only available on Web.                                                                                                                                                          |                                                                                                                                                                                                                                                                                              | 8.3.0 |
| **`cookielessMode`**                    | \`'always'             | 'on_reject'\`                                                                                                                                                                                                                                      | Cookieless tracking mode. - `'always'`: Always use cookieless tracking with server-side anonymous hash. - `'on_reject'`: Normal tracking until `optOut()` is called, then switches to cookieless. Only available on Web. Requires cookieless mode to be enabled in PostHog project settings. |       |
| **`enableSessionReplay`**               | `boolean`              | Whether to enable session recording automatically.                                                                                                                                                                                                 | `false`                                                                                                                                                                                                                                                                                      | 7.3.0 |
| **`optOut`**                            | `boolean`              | Whether to opt out of capturing by default. User must call `optIn()` to enable capturing.                                                                                                                                                          | `false`                                                                                                                                                                                                                                                                                      | 8.1.0 |
| **`sessionReplayConfig`**               | `SessionReplayOptions` | Session replay configuration options.                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                              | 7.3.0 |
| **`captureApplicationLifecycleEvents`** | `boolean`              | Whether to capture application lifecycle events. Only available on iOS and Android.                                                                                                                                                                | `true`                                                                                                                                                                                                                                                                                       | 8.3.0 |
| **`autoCaptureExceptions`**             | `boolean`              | Whether to automatically capture unhandled exceptions.                                                                                                                                                                                             | `false`                                                                                                                                                                                                                                                                                      | 8.5.0 |
| **`preloadFeatureFlags`**               | `boolean`              | Whether to preload feature flags on startup. Only available on Android and iOS.                                                                                                                                                                    | `true`                                                                                                                                                                                                                                                                                       | 8.6.0 |
| **`surveys`**                           | `boolean`              | Whether to enable surveys. Only available on iOS and Web.                                                                                                                                                                                          | `true`                                                                                                                                                                                                                                                                                       | 8.6.0 |
| **`webConfig`**                         | `Record<string, any>`  | Additional [posthog-js configuration options](https://posthog.com/docs/libraries/js/config) that are merged into the configuration passed to `posthog.init`. Options set here take precedence over the other setup options. Only available on Web. |                                                                                                                                                                                                                                                                                              | 8.6.0 |

#### SessionReplayOptions

| Prop                          | Type      | Description                                                                                     | Default | Since |
| ----------------------------- | --------- | ----------------------------------------------------------------------------------------------- | ------- | ----- |
| **`screenshotMode`**          | `boolean` | Enable screenshot mode for session recordings. WARNING: This may capture sensitive information. | `false` | 7.3.0 |
| **`maskAllTextInputs`**       | `boolean` | Mask all text input fields in session recordings.                                               | `true`  | 7.3.0 |
| **`maskAllImages`**           | `boolean` | Mask all images in session recordings.                                                          | `true`  | 7.3.0 |
| **`maskAllSandboxedViews`**   | `boolean` | Mask all sandboxed system views (iOS-specific).                                                 | `true`  | 7.3.0 |
| **`captureNetworkTelemetry`** | `boolean` | Capture network telemetry in session recordings.                                                | `false` | 7.3.0 |
| **`debouncerDelay`**          | `number`  | Debounce delay for session recording snapshots (in seconds).                                    | `1.0`   | 7.3.0 |

#### UnregisterOptions

| Prop      | Type     | Description                               | Since |
| --------- | -------- | ----------------------------------------- | ----- |
| **`key`** | `string` | The name of the super property to remove. | 6.0.0 |

### Type Aliases

#### JsonType

`string | number | boolean | null | { [key: string]: JsonType; } | JsonType[]`

## Advanced

### Reverse Proxy

For PostHog managed reverse proxy, set `apiHost` to your proxy URL and `uiHost` to your PostHog app host (`https://us.posthog.com` or `https://eu.posthog.com`). `host` remains supported as a deprecated alias for `apiHost`. `uiHost` is only available on Web.

## FAQ

### Do I have to call the `setup` method before using the plugin?

Yes, the `setup(...)` method should be called before any other method. Alternatively, on Android and iOS, you can configure the plugin in your Capacitor configuration file (see [Configuration](#configuration)). In that case, you must not call the `setup(...)` method.

### What is the difference between the `apiHost` and `host` options?

The `host` option is a deprecated alias for `apiHost`. Both point to the API host of your PostHog instance or reverse proxy. If both options are provided, `apiHost` takes precedence, so new projects should only use `apiHost`.

### How do I use the plugin with a reverse proxy?

Set the `apiHost` option to your proxy URL and the `uiHost` option to your PostHog app host, such as `https://us.posthog.com` or `https://eu.posthog.com`. Note that `uiHost` is only available on Web. See the [Reverse Proxy](#reverse-proxy) section for more details.

### How do I enable session replay?

Set the `enableSessionReplay` option to `true` in the `setup(...)` method or in your Capacitor configuration file, and fine-tune the recording behavior with the `sessionReplayConfig` option. You can also start and stop recording manually using the `startSessionRecording()` and `stopSessionRecording()` methods.

### How can users opt out of tracking?

Call the `optOut()` method to stop event capturing and the `optIn()` method to re-enable it. You can check the current state with `isOptOut()` or opt users out by default with the `optOut` setup option. On Web with `cookielessMode: 'on_reject'`, opting out switches to cookieless anonymous tracking instead of stopping capturing entirely.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Unofficial Capacitor plugin for Firebase Analytics.
- [Crisp](https://capawesome.io/docs/sdks/capacitor/crisp/): Unofficial Capacitor plugin for the Crisp live chat and customer support platform.
- [Formbricks](https://capawesome.io/docs/sdks/capacitor/formbricks/): Unofficial Capacitor plugin for Formbricks to run in-app surveys.
- [Grafana Faro](https://capawesome.io/docs/sdks/capacitor/grafana-faro/): Unofficial Capacitor plugin for Grafana Faro to monitor your app.
- [TikTok App Events](https://capawesome.io/docs/sdks/capacitor/tiktok-app-events/): Unofficial Capacitor plugin for the TikTok App Events SDK.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by PostHog, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Printer Plugin

Capacitor plugin for seamless printing on Android and iOS. Supports base64, files, HTML, PDFs, and web views.

## Features

The Capacitor Printer plugin is one of the most complete printing solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🖨️ **Base64 Printer**: Print base64 encoded files.
- 🖨️ **File Printer**: Print files from the device.
- 🖨️ **HTML Printer**: Print custom HTML content.
- 🖨️ **PDF Printer**: Print PDF files.
- 🖨️ **Web View Printer**: Print web view content.
- ⚔️ **Battle-Tested**: Used in more than 100 projects.
- 🤝 **Compatibility**: Works alongside the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/), [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/) and [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Printer plugin is typically used whenever an app needs to send content to a printer, for example:

- **Receipts and invoices**: Print HTML-formatted receipts or invoices directly from your app.
- **Documents**: Print PDF documents or other files stored on the device.
- **Server-generated content**: Print documents received from an API as base64 encoded data.
- **Reports and summaries**: Print the current web view content, customized with a print style sheet.

## 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     |

## Demo

A working example can be found [here](https://github.com/robingenz/capacitor-plugin-demo).

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Exploring the Capacitor Printer API](https://capawesome.io/blog/exploring-the-capacitor-printer-api/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-printer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-printer
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$androidxDocumentFileVersion` version of `androidx.documentfile:documentfile` (default: `1.1.0`)
- `$androidxPrintVersion` version of `androidx.print:print` (default: `1.1.0`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to print a file from the device, a base64 encoded file, custom HTML content, a PDF document, and the web view content.

### Print a file from the device

Present the printing user interface to print a file stored on the device, for example a file the user previously downloaded. Only available on Android and iOS:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printFile = async () => {
  await Printer.printFile({
    mimeType: 'application/pdf',
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000485',
  });
};
```

### Print a base64 encoded file

Print a file that is only available as a base64 encoded string, for example a document received from an API. Note that large files can lead to app crashes, so it's recommended to use the `printFile(...)` method instead whenever possible. Only available on Android and iOS:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printBase64 = async () => {
  await Printer.printBase64({
    name: 'My Document',
    data: 'JVBERi0...',
  });
};
```

### Print custom HTML content

Print custom HTML content, for example a receipt or invoice rendered by your app. Only available on Android and iOS:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printHtml = async () => {
  await Printer.printHtml({
    name: 'My Document',
    html: '<h1>Hello World</h1>',
  });
};
```

### Print a PDF document

Print a PDF document stored on the device. Only available on Android and iOS:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printPdf = async () => {
  await Printer.printPdf({
    name: 'My Document',
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000485',
  });
};
```

### Print the web view content

Print the current content of the web view. You can use a [print style sheet](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing) to customize the print output:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printWebView = async () => {
  await Printer.printWebView({
    name: 'My Document',
  });
};
```

## API

- [`printBase64(...)`](#printbase64)
- [`printFile(...)`](#printfile)
- [`printHtml(...)`](#printhtml)
- [`printPdf(...)`](#printpdf)
- [`printWebView(...)`](#printwebview)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### printBase64(...)

```
printBase64(options: PrintBase64Options) => Promise<void>
```

Present the printing user interface to print files encoded as base64 strings.

**Attention**: Large files can lead to app crashes. It's therefore recommended to use the `printFile` method instead.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `PrintBase64Options` |

**Since:** 7.1.0

______________________________________________________________________

### printFile(...)

```
printFile(options: PrintFileOptions) => Promise<void>
```

Present the printing user interface to print files.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PrintFileOptions` |

**Since:** 7.1.0

______________________________________________________________________

### printHtml(...)

```
printHtml(options: PrintHtmlOptions) => Promise<void>
```

Present the printing user interface to print a html document.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PrintHtmlOptions` |

**Since:** 5.0.0

______________________________________________________________________

### printPdf(...)

```
printPdf(options: PrintPdfOptions) => Promise<void>
```

Present the printing user interface to print a pdf document.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `PrintPdfOptions` |

**Since:** 5.1.0

______________________________________________________________________

### printWebView(...)

```
printWebView(options?: PrintOptions | undefined) => Promise<void>
```

Present the printing user interface to print the web view content.

You can use a print style sheet to customize the print output (see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing).

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `PrintOptions` |

**Since:** 5.0.0

______________________________________________________________________

### Interfaces

#### PrintBase64Options

| Prop           | Type     | Description                                                                                                                                               | Since |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`data`**     | `string` | A valid base 64 encoded string.                                                                                                                           | 7.1.0 |
| **`mimeType`** | `string` | The mime type of the data. The following mime types are supported: `application/pdf`, `image/gif`, `image/heic`, `image/heif`, `image/jpeg`, `image/png`. | 7.1.0 |

#### PrintFileOptions

| Prop           | Type     | Description                                           | Since |
| -------------- | -------- | ----------------------------------------------------- | ----- |
| **`mimeType`** | `string` | The mime type of the file. Only available on Android. | 7.1.0 |
| **`path`**     | `string` | The path to the file.                                 | 7.1.0 |

#### PrintHtmlOptions

| Prop       | Type     | Description                | Since |
| ---------- | -------- | -------------------------- | ----- |
| **`html`** | `string` | The HTML content to print. | 5.0.0 |

#### PrintPdfOptions

| Prop       | Type     | Description                                 | Since |
| ---------- | -------- | ------------------------------------------- | ----- |
| **`path`** | `string` | The path to the pdf document on the device. | 5.1.0 |

#### PrintOptions

| Prop       | Type     | Description                | Default      | Since |
| ---------- | -------- | -------------------------- | ------------ | ----- |
| **`name`** | `string` | The name of the print job. | `'Document'` | 5.0.0 |

### Type Aliases

#### PrintWebViewOptions

`PrintOptions`

## FAQ

### Can I print on the web?

On the web, only the `printWebView(...)` method is available, which prints the current web view content. The `printBase64(...)`, `printFile(...)`, `printHtml(...)` and `printPdf(...)` methods are only available on Android and iOS.

### Why does my app crash when printing large base64 files?

The `printBase64(...)` method loads the entire file into memory, which can lead to app crashes for large files. It's therefore recommended to use the `printFile(...)` method instead, which prints the file directly from its path on the device.

### Which file types can I print?

The `printBase64(...)` method supports the mime types `application/pdf`, `image/gif`, `image/heic`, `image/heif`, `image/jpeg`, and `image/png`. In addition, you can print arbitrary files from the device with `printFile(...)`, PDF documents with `printPdf(...)`, custom HTML content with `printHtml(...)`, and the current web view content with `printWebView(...)`.

### How can I customize the print output of the web view?

You can use a print style sheet to customize how the web view content is printed, for example to hide navigation elements or adjust the layout. Check out the [MDN documentation on printing](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing) for more information.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file to print from the device's file system.
- [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/): Generate paginated PDF files from HTML content or URLs.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/printer/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/printer/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/printer/LICENSE).

# Capacitor Privacy Screen Plugin

Capacitor plugin to hide sensitive app content in the app switcher, block screenshots, and detect when a screenshot is taken.

## Features

- 🖼️ **App switcher**: Hide sensitive app content in the app switcher.
- 📸 **Screenshot prevention**: Block screenshots and screen recordings.
- 🔔 **Screenshot detection**: Get notified when the user takes a screenshot.
- 🤝 **Compatibility**: Works alongside the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) and [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Privacy Screen plugin is typically used in apps that display sensitive information, for example:

- **Banking and finance apps**: Hide account balances and transactions in the app switcher and block screenshots.
- **Password managers**: Prevent credentials from appearing in screenshots or screen recordings.
- **Messaging and health apps**: Protect private conversations and medical data from being captured.
- **Screenshot auditing**: Get notified via the `screenshotTaken` event when the user takes a screenshot, for example to log the event or warn the user.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here [capawesome-team/capacitor-privacy-screen-demo](https://github.com/capawesome-team/capacitor-privacy-screen-demo).

## Guides

- [Capacitor Privacy Screen: Hide Sensitive App Content](https://capawesome.io/blog/capacitor-privacy-screen-hide-app-content/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-privacy-screen` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-privacy-screen
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

### Android

#### Permissions

The plugin declares the `android.permission.DETECT_SCREEN_CAPTURE` permission in its `AndroidManifest.xml`. This install-time permission is required to detect screenshots on Android 14 (API level 34) and newer. It is added automatically and requires no further configuration.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to enable and disable the privacy screen, check whether it is enabled, and detect screenshots.

### Enable the privacy screen

Enable the privacy screen to hide the app content in the app switcher. On Android, this also blocks screenshots and screen recordings. On iOS, screenshots are only blocked if the `ios.preventScreenshots` option is enabled:

```
import { PrivacyScreen } from '@capawesome/capacitor-privacy-screen';

const enable = async () => {
  await PrivacyScreen.enable({
    ios: {
      preventScreenshots: true,
    },
  });
};
```

### Disable the privacy screen

Disable the privacy screen when it is no longer needed:

```
import { PrivacyScreen } from '@capawesome/capacitor-privacy-screen';

const disable = async () => {
  await PrivacyScreen.disable();
};
```

### Check whether the privacy screen is enabled

Check if the privacy screen is currently enabled:

```
import { PrivacyScreen } from '@capawesome/capacitor-privacy-screen';

const isEnabled = async () => {
  const { enabled } = await PrivacyScreen.isEnabled();
  return enabled;
};
```

### Detect screenshots

Get notified when the user takes a screenshot of the app. On Android, this event is only emitted on Android 14 (API level 34) and newer:

```
import { PrivacyScreen } from '@capawesome/capacitor-privacy-screen';

const addListener = async () => {
  await PrivacyScreen.addListener('screenshotTaken', () => {
    console.log('The user took a screenshot.');
  });
};

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

## API

- [`disable()`](#disable)
- [`enable(...)`](#enable)
- [`isEnabled()`](#isenabled)
- [`addListener('screenshotTaken', ...)`](#addlistenerscreenshottaken-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### disable()

```
disable() => Promise<void>
```

Disable the privacy screen.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### enable(...)

```
enable(options?: EnableOptions | undefined) => Promise<void>
```

Enable the privacy screen.

On Android, this sets the `FLAG_SECURE` flag on the window, which hides the app content in the app switcher and blocks screenshots and screen recordings.

On iOS, this installs an overlay that hides the app content in the app switcher. Screenshots are only blocked if the `ios.preventScreenshots` option is enabled.

Only available on Android and iOS.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `EnableOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Check whether the privacy screen is currently enabled.

Only available on Android and iOS.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('screenshotTaken', ...)

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

Listen for when the user takes a screenshot of the app.

The event can only be observed after the screenshot has been taken and therefore cannot be prevented.

On Android, this event is only emitted on Android 14 (API level 34) and newer. On older versions, the listener is never called.

Only available on Android and iOS.

| Param              | Type                |
| ------------------ | ------------------- |
| **`eventName`**    | `'screenshotTaken'` |
| **`listenerFunc`** | `() => void`        |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### EnableOptions

| Prop      | Type               | Description                                                  | Since |
| --------- | ------------------ | ------------------------------------------------------------ | ----- |
| **`ios`** | `EnableIosOptions` | Options that are only applied on iOS. Only available on iOS. | 0.1.0 |

#### EnableIosOptions

| Prop                     | Type      | Description                                                                                                                                                                                                                   | Default | Since |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`preventScreenshots`** | `boolean` | Whether to block screenshots while the privacy screen is enabled. There is no official iOS API to prevent screenshots. This uses an unofficial technique that may stop working in future iOS versions. Only available on iOS. | `false` | 0.1.0 |

#### IsEnabledResult

| Prop          | Type      | Description                                      | Since |
| ------------- | --------- | ------------------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether the privacy screen is currently enabled. | 0.1.0 |

#### PluginListenerHandle

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

## Capabilities

The capabilities of this plugin differ between platforms. The following table gives an honest overview of what is supported:

| Capability                       | Android               | iOS                                      |
| -------------------------------- | --------------------- | ---------------------------------------- |
| Hide content in the app switcher | ✅ (via `enable()`)   | ✅ (via `enable()`)                      |
| Block screenshots                | ✅ (via `enable()`)   | ⚠️ (opt-in via `ios.preventScreenshots`) |
| Detect screenshots               | ✅ (Android 14+ only) | ✅                                       |

**Android**: The `enable()` method sets the `FLAG_SECURE` window flag, which hides the app content in the app switcher and blocks both screenshots and screen recordings with a single flag. Screenshot detection is only available on Android 14 (API level 34) and newer; on older versions the `screenshotTaken` event is never emitted.

**iOS**: The `enable()` method installs an overlay that hides the app content in the app switcher. There is no official API to block screenshots. When `ios.preventScreenshots` is enabled, the plugin uses an unofficial secure text field technique that may stop working in future iOS versions. Screenshot detection observes `UIApplication.userDidTakeScreenshotNotification`, which only fires **after** the screenshot has been taken and therefore cannot be prevented.

## FAQ

### How is this plugin different from other similar plugins?

It combines three protections in one fully typed API — hiding sensitive content in the app switcher, blocking screenshots and screen recordings, and detecting when a screenshot is taken — across both Android and iOS. It's honest about what each platform can actually guarantee, with a clear capability table and opt-in handling for the areas where iOS has no official API, so you always know the real behavior you're getting. The API is actively maintained against the latest Capacitor and OS versions.

### Can this plugin block screenshots on iOS?

Yes, but only as an opt-in. There is no official iOS API to prevent screenshots, so the plugin uses an unofficial secure text field technique that may stop working in future iOS versions. You can enable it via the `ios.preventScreenshots` option of the `enable(...)` method. On Android, screenshots are blocked reliably via the `FLAG_SECURE` window flag.

### Can I prevent a screenshot instead of just detecting it?

On Android, yes: calling `enable(...)` sets the `FLAG_SECURE` window flag, which blocks both screenshots and screen recordings. On iOS, the `screenshotTaken` event can only be observed after the screenshot has been taken and therefore cannot be prevented; blocking is only possible via the opt-in `ios.preventScreenshots` option.

### Does the privacy screen appear during permission or biometric prompts on iOS?

No. On iOS, the overlay is only installed when the app actually enters the background, not when it merely becomes inactive. System dialogs such as permission prompts, Face ID or Touch ID prompts, incoming calls, the Control Center and the Notification Center therefore leave the app content visible.

### Why is the `screenshotTaken` event never emitted on my Android device?

On Android, screenshot detection is only available on Android 14 (API level 34) and newer. On older Android versions, the listener is never called. On iOS, the event is available without version restrictions.

### Does this plugin work on the Web?

No, this plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented since browsers do not provide APIs to control the app switcher or screenshots.

### Do I need to configure any permissions?

No, the plugin declares the `android.permission.DETECT_SCREEN_CAPTURE` install-time permission in its own `AndroidManifest.xml`, which is required to detect screenshots on Android 14 and newer. It is added automatically and requires no further configuration. On iOS, no permissions are required.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API and App Attest.
- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/privacy-screen/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/privacy-screen/LICENSE).

# Capacitor Proximity Sensor Plugin

Capacitor plugin to read the device's proximity sensor.

## Features

The Capacitor Proximity Sensor plugin is one of the most complete proximity sensing solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📏 **Proximity detection**: Detect whether an object is close to the screen.
- ⚡ **Real-time updates**: Continuous proximity data with event listeners.
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/) and [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Proximity Sensor plugin is typically used to react when an object is close to the device's screen, for example:

- **Calling and VoIP apps**: Detect when the user holds the device to their ear during a call.
- **Pocket detection**: Detect when the device is in a pocket or bag to ignore accidental input.
- **Proximity-triggered actions**: Start or stop app behavior based on real-time `measurement` events.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How proximity events pair with the Light Sensor in call and media apps that adapt to the environment.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-proximity-sensor` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-proximity-sensor
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the proximity sensor is available, get a single measurement, and start and stop continuous measurement updates.

### Check whether the sensor is available

Not every device has a proximity sensor, so check its availability first. Only available on Android and iOS:

```
import { ProximitySensor } from '@capawesome/capacitor-proximity-sensor';

const isAvailable = async () => {
  const result = await ProximitySensor.isAvailable();
  return result.available;
};
```

### Get a single measurement

Read the most recent measurement from the proximity sensor. Note that on iOS, reading the measurement enables proximity monitoring, which turns off the screen while an object is close to the sensor (see [Screen Dimming (iOS)](#screen-dimming-ios)):

```
import { ProximitySensor } from '@capawesome/capacitor-proximity-sensor';

const getMeasurement = async () => {
  const measurement = await ProximitySensor.getMeasurement();
  console.log('Near: ', measurement.near);
  console.log('Distance: ', measurement.distance);
};
```

### Start and stop measurement updates

Listen for continuous `measurement` events. On iOS, proximity monitoring stays enabled until `stopMeasurementUpdates()` (or `removeAllListeners()`) is called:

```
import { ProximitySensor } from '@capawesome/capacitor-proximity-sensor';

const startMeasurementUpdates = async () => {
  await ProximitySensor.addListener('measurement', measurement => {
    console.log('Near: ', measurement.near);
    console.log('Distance: ', measurement.distance);
  });
  await ProximitySensor.startMeasurementUpdates();
};

const stopMeasurementUpdates = async () => {
  await ProximitySensor.stopMeasurementUpdates();
};

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

## API

- [`getMeasurement()`](#getmeasurement)
- [`isAvailable()`](#isavailable)
- [`startMeasurementUpdates()`](#startmeasurementupdates)
- [`stopMeasurementUpdates()`](#stopmeasurementupdates)
- [`addListener('measurement', ...)`](#addlistenermeasurement-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getMeasurement()

```
getMeasurement() => Promise<GetMeasurementResult>
```

Get the latest measurement.

This method returns the most recent measurement from the proximity sensor.

On iOS, reading the measurement enables proximity monitoring, which turns off the screen while an object is close to the sensor.

Only available on Android and iOS.

**Returns:** `Promise<Measurement>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the proximity sensor is available on the device.

Only available on Android and iOS.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### startMeasurementUpdates()

```
startMeasurementUpdates() => Promise<void>
```

Start emitting `measurement` events.

On iOS, this enables proximity monitoring, which turns off the screen while an object is close to the sensor.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### stopMeasurementUpdates()

```
stopMeasurementUpdates() => Promise<void>
```

Stop emitting `measurement` events.

On iOS, this disables proximity monitoring.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('measurement', ...)

```
addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new measurement is available.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'measurement'`                |
| **`listenerFunc`** | `(event: Measurement) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### Measurement

| Prop           | Type      | Description                               | Since                                                                                                                                                                                                                                                                    |
| -------------- | --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`distance`** | \`number  | null\`                                    | The distance between the sensor and the nearby object in centimeters (cm). Most devices only report whether an object is near or far, so this value is typically either `0` (near) or the sensor's maximum range (far). Only available on Android. Always `null` on iOS. |
| **`near`**     | `boolean` | Whether an object is close to the sensor. | 0.1.0                                                                                                                                                                                                                                                                    |

#### IsAvailableResult

| Prop            | Type      | Description                                              | Since |
| --------------- | --------- | -------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether the proximity sensor is available on the device. | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### GetMeasurementResult

`Measurement`

#### MeasurementEvent

`Measurement`

## Screen Dimming (iOS)

On iOS, reading the proximity sensor requires enabling proximity monitoring via `UIDevice`. While monitoring is enabled, iOS automatically turns off the screen whenever an object (such as the user's ear or a hand) is close to the sensor, exactly like during a phone call. This is a system-level behavior that cannot be disabled.

For this reason, monitoring is only enabled while it is needed:

- `getMeasurement()` enables monitoring, reads the current state and disables it again.
- `startMeasurementUpdates()` keeps monitoring enabled until `stopMeasurementUpdates()` (or `removeAllListeners()`) is called.

Only call `startMeasurementUpdates()` when you actually want this behavior.

On Android, reading the proximity sensor has no effect on the screen.

## FAQ

### How is this plugin different from other similar plugins?

It covers the whole proximity story through one fully typed API: a one-time reading, continuous real-time `measurement` events, and an availability check, working consistently across Android and iOS. It surfaces platform specifics honestly — a distance in centimeters on Android and the near/far state on iOS — and documents the iOS screen-dimming behavior so there are no surprises. The package is kept current with the latest Capacitor version and ships for both CocoaPods and Swift Package Manager.

### Why does the screen turn off on iOS when reading the sensor?

On iOS, reading the proximity sensor requires enabling proximity monitoring via `UIDevice`. While monitoring is enabled, iOS automatically turns off the screen whenever an object is close to the sensor, exactly like during a phone call. This is a system-level behavior that cannot be disabled. See the [Screen Dimming (iOS)](#screen-dimming-ios) section for details.

### Why is the `distance` value always `null` on iOS?

iOS only reports whether an object is near the sensor via the `near` property. The `distance` value in centimeters is only available on Android and is always `null` on iOS.

### Why is the `distance` value always either `0` or the maximum range on Android?

Most devices only report whether an object is near or far instead of an exact distance. The `distance` value is therefore typically either `0` (near) or the sensor's maximum range (far).

### How can I check whether a device has a proximity sensor?

Call the `isAvailable()` method before using the sensor. It returns whether the proximity sensor is available on the device.

### Does this plugin work on the Web?

No, this plugin is only available on Android and iOS, since browsers do not expose the device's proximity sensor.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure in hectopascals (hPa).
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.
- [Light Sensor](https://capawesome.io/docs/sdks/capacitor/light-sensor/): Read the device's ambient light sensor.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/proximity-sensor/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/proximity-sensor/LICENSE).

# Capacitor Purchases Plugin

Capacitor plugin to support in-app purchases.

## Features

The Capacitor Purchases plugin is one of the most complete in-app purchase solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🛍️ **Product Types**: Supports subscriptions, consumables, and non-consumable in-app products.
- 🗂️ **Product Retrieval**: Fetch multiple products in a single call for efficient loading.
- 🎁 **Intro Offer Eligibility**: Check if introductory offers are available for subscription products.
- 📅 **Billing Plans**: Supports monthly-with-12-month-commitment subscriptions on iOS (26.4+).
- 🔒 **Server Validation**: Provides verification tokens (iOS JWS, Android purchase tokens) for server-side validation.
- 🔗 **Third-Party Validation**: Includes transaction properties for third-party validation.
- 📋 **Transaction Management**: Track current, unfinished, and historical transactions.
- 🔄 **Purchase Restoration**: Easily sync and restore purchases across devices.
- 🚀 **Modern APIs**: Uses StoreKit 2 and Google Play Billing Library 8.0.
- 🚨 **Error Codes**: Provides detailed error codes for better error handling.
- 🤝 **Compatibility**: Works alongside the [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/) and [Superwall](https://capawesome.io/docs/sdks/capacitor/superwall/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll add it for you!

## Use Cases

The Purchases plugin is typically used whenever an app wants to monetize with in-app purchases, for example:

- **Premium subscriptions**: Sell auto-renewable subscriptions and check whether an introductory offer is available for a product.
- **One-time unlocks**: Sell consumable and non-consumable in-app products, such as feature unlocks or in-app currency.
- **Server-side validation**: Pass the verification tokens (JWS on iOS, purchase tokens on Android) to your backend to validate purchases.
- **Purchase restoration**: Sync and restore purchases so users keep their content across devices.
- **Reliable transaction handling**: Track current, unfinished, and historical transactions to make sure every purchase is delivered.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.4.x          | >=8.x.x           | Active support |
| 0.3.x          | >=8.x.x           | Deprecated     |
| 0.2.x          | >=8.x.x           | Deprecated     |

## Prerequisites

### iOS

Xcode 26.5 or later is required to build the plugin.

## Guides

- [Tips for Setting Up In-App Purchases with Capacitor](https://capawesome.io/blog/tips-for-setting-up-in-app-purchases-with-capacitor/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-purchases` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-purchases
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$googlePlayBillingVersion` version of `com.android.billingclient:billing` (default: `8.2.0`)

### iOS

#### Capabilities

Ensure `In-App Purchase` capabilities have been enabled in your application in Xcode. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to purchase a product and restore previous purchases.

### Purchase a product

Purchase a product by its ID and finish the transaction after the content has been delivered or the service has been enabled. On Android, this is the product ID configured in the Google Play Console. On iOS, this is the product ID configured in App Store Connect. On Android, set `isConsumable` to `true` when finishing the purchase of a consumable so that it can be purchased again. Only available on Android, and on iOS 15.0 and later:

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const purchaseProduct = async (productId: string) => {
  const { transaction } = await Purchases.purchaseProduct({ productId });
  // Deliver the purchased content or enable the service here
  // ...
  // Finish the transaction
  await Purchases.finishTransaction({ transactionId: transaction.id });
  // On Android, pass `isConsumable: true` for consumable products only:
  // await Purchases.finishTransaction({ transactionId: transaction.id, isConsumable: true });
};
```

### Restore previous purchases

Sync the transactions with the store and retrieve the currently owned items to restore purchases across devices. On iOS, `syncTransactions()` displays a system dialog asking the user to authenticate, so call it only in response to an explicit user action. Only available on Android, and on iOS 15.0 and later:

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const restorePurchases = async () => {
  await Purchases.syncTransactions();
  const { transactions } = await Purchases.getCurrentTransactions();
  for (const transaction of transactions) {
    // Deliver the purchased content or enable the service here
    // ...
  }
};
```

## API

- [`finishTransaction(...)`](#finishtransaction)
- [`getAllTransactions()`](#getalltransactions)
- [`getCurrentTransactions()`](#getcurrenttransactions)
- [`getProductById(...)`](#getproductbyid)
- [`getProductsByIds(...)`](#getproductsbyids)
- [`getUnfinishedTransactions()`](#getunfinishedtransactions)
- [`isAvailable()`](#isavailable)
- [`isIntroOfferAvailableForProduct(...)`](#isintroofferavailableforproduct)
- [`purchaseProduct(...)`](#purchaseproduct)
- [`syncTransactions()`](#synctransactions)
- [Interfaces](#interfaces)
- [Enums](#enums)

### finishTransaction(...)

```
finishTransaction(options: FinishTransactionOptions) => Promise<void>
```

Finish a transaction.

Indicates to the store that the app delivered the purchased content or enabled the service to finish the transaction.

On **Android**, the purchase is acknowledged, or consumed if `isConsumable` is set to `true`. A consumed purchase can be purchased again and is no longer returned by `getCurrentTransactions()`.

Only available on Android and iOS (15.0+).

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `FinishTransactionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getAllTransactions()

```
getAllTransactions() => Promise<GetAllTransactionsResult>
```

Returns transaction details for all transactions made by the user within your app.

Only available on iOS (15.0+).

**Returns:** `Promise<GetAllTransactionsResult>`

**Since:** 0.1.0

______________________________________________________________________

### getCurrentTransactions()

```
getCurrentTransactions() => Promise<GetCurrentTransactionsResult>
```

Returns transaction details for currently owned items bought within your app.

Only active subscriptions and non-consumed one-time purchases are returned.

On **iOS**, transactions that could not be verified by the App Store are not included.

Only available on Android and iOS (15.0+).

**Returns:** `Promise<GetCurrentTransactionsResult>`

**Since:** 0.1.0

______________________________________________________________________

### getProductById(...)

```
getProductById(options: GetProductByIdOptions) => Promise<GetProductByIdResult>
```

Get product details by product ID.

Only available on Android and iOS (15.0+).

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetProductByIdOptions` |

**Returns:** `Promise<GetProductByIdResult>`

**Since:** 0.3.1

______________________________________________________________________

### getProductsByIds(...)

```
getProductsByIds(options: GetProductsByIdsOptions) => Promise<GetProductsByIdsResult>
```

Get product details for multiple products by their IDs.

Only available on Android and iOS (15.0+).

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `GetProductsByIdsOptions` |

**Returns:** `Promise<GetProductsByIdsResult>`

**Since:** 0.3.3

______________________________________________________________________

### getUnfinishedTransactions()

```
getUnfinishedTransactions() => Promise<GetUnfinishedTransactionsResult>
```

Returns transaction details for all transactions that are not yet finished.

Check for unfinished transactions at least once every app launch and whenever the app returns to the foreground to pick up purchases that were completed in the meantime, for example pending purchases.

Only available on Android and iOS (15.0+).

**Returns:** `Promise<GetUnfinishedTransactionsResult>`

**Since:** 0.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if in-app purchases are supported on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 0.1.0

______________________________________________________________________

### isIntroOfferAvailableForProduct(...)

```
isIntroOfferAvailableForProduct(options: IsIntroOfferAvailableForProductOptions) => Promise<IsIntroOfferAvailableForProductResult>
```

Check if an introductory offer is available for a product.

On **iOS**, this uses StoreKit 2's `isEligibleForIntroOffer` to check if the customer has already used an introductory offer for any subscription within the same subscription group.

On **Android**, this checks if the product has any introductory pricing phases available. Google Play automatically filters offers based on eligibility when querying products, so if an intro offer is present, the user can purchase it.

Only available on Android and iOS.

| Param         | Type                                     |
| ------------- | ---------------------------------------- |
| **`options`** | `IsIntroOfferAvailableForProductOptions` |

**Returns:** `Promise<IsIntroOfferAvailableForProductResult>`

**Since:** 0.3.2

______________________________________________________________________

### purchaseProduct(...)

```
purchaseProduct(options: PurchaseProductOptions) => Promise<PurchaseProductResult>
```

Purchase a product by its ID.

Make sure to call `finishTransaction(...)` after the purchase is complete and the content has been delivered or the service has been enabled.

The call is rejected with the `PENDING` error code if the purchase requires further action from the user, for example an additional payment step. The transaction is returned by `getUnfinishedTransactions()` once the purchase is complete.

On **Android**, the call is rejected with the `PRODUCT_ALREADY_OWNED` error code if the product is already owned and with the `PRODUCT_UNAVAILABLE` error code if the product is not available for purchase.

On **iOS**, the call is rejected with the `VERIFICATION_FAILED` error code if the App Store could not verify the transaction.

Only available on Android and iOS (15.0+).

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `PurchaseProductOptions` |

**Returns:** `Promise<PurchaseProductResult>`

**Since:** 0.1.0

______________________________________________________________________

### syncTransactions()

```
syncTransactions() => Promise<void>
```

Sync transactions with the App Store.

This method is used to ensure that all transactions are up-to-date and methods like `getCurrentTransactions` return the latest transactions.

On **iOS**, calling this method will display a system dialog to the user asking them to authenticate with their App Store credentials. Call this method only in response to an explicit user action.

On **Android**, this method silently queries and refreshes purchases from Google Play without user interaction.

Only available on Android and iOS (15.0+).

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### FinishTransactionOptions

| Prop                | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          | Default | Since |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`isConsumable`**  | `boolean` | Whether the purchased product is a consumable. Google Play cannot distinguish consumables from non-consumables, so set this to `true` to consume the purchase instead of acknowledging it. Only set this for consumable one-time products and never for subscriptions, which are acknowledged and never consumed. Non-consumables must be acknowledged as well. On **iOS**, the App Store already knows the product type. Only available on Android. | `false` | 0.4.0 |
| **`transactionId`** | `string`  | The ID of the transaction to finish. On **Android**, the purchase token (see [`Transaction.token`](#transaction)) is accepted as well.                                                                                                                                                                                                                                                                                                               |         | 0.1.0 |

#### GetAllTransactionsResult

| Prop               | Type            | Description                    | Since |
| ------------------ | --------------- | ------------------------------ | ----- |
| **`transactions`** | `Transaction[]` | The transactions for the user. | 0.1.0 |

#### Transaction

| Prop                     | Type                        | Description                                                                                                                                                                                                                                                                                                                            | Since |
| ------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**                 | `string`                    | The unique identifier for the transaction. On **Android**, this is the purchase token as long as Google Play has not assigned an order ID yet (e.g. for pending purchases), and the Google Play order ID afterwards. Use `token` as the stable key to correlate a purchase over time. On **iOS**, this is the StoreKit transaction ID. | 0.1.0 |
| **`verificationResult`** | `string`                    | The JWS (JSON Web Signature) representation of the transaction verification result. Pass this to your server to validate the purchase. If the transaction could not be verified, this will not be present. Only available on iOS.                                                                                                      | 0.1.0 |
| **`token`**              | `string`                    | A unique identifier that represents the user and the product ID for the in-app product they purchased. Pass this to your server to validate the purchase. Only available on Android.                                                                                                                                                   | 0.2.1 |
| **`productId`**          | `string`                    | The product identifier associated with the transaction.                                                                                                                                                                                                                                                                                | 0.3.2 |
| **`originalJson`**       | `string`                    | The original JSON purchase data. Pass this to your server to validate the purchase. Only available on Android.                                                                                                                                                                                                                         | 0.3.2 |
| **`signature`**          | `string`                    | The RSA signature for purchase verification. Pass this to your server to validate the purchase. Only available on Android.                                                                                                                                                                                                             | 0.3.2 |
| **`planType`**           | `BillingPlanType`           | The billing plan type the user committed to when this transaction was made. Only available on iOS (26.4+).                                                                                                                                                                                                                             | 0.3.8 |
| **`commitmentInfo`**     | `TransactionCommitmentInfo` | The commitment details for transactions made under a billing plan that includes a commitment (e.g. monthly with 12-month commitment). Only available on iOS (26.4+).                                                                                                                                                                   | 0.3.8 |

#### TransactionCommitmentInfo

The commitment details for a transaction.

| Prop                      | Type     | Description                                                             | Since |
| ------------------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`billingPeriodNumber`** | `number` | The 1-based number of the current billing period within the commitment. | 0.3.8 |
| **`totalBillingPeriods`** | `number` | The total number of billing periods in the commitment.                  | 0.3.8 |
| **`expirationDate`**      | `string` | The date the commitment expires, as an ISO 8601 string.                 | 0.3.8 |
| **`price`**               | `number` | The price charged for this billing period, as a decimal number.         | 0.3.8 |

#### GetCurrentTransactionsResult

| Prop               | Type            | Description                            | Since |
| ------------------ | --------------- | -------------------------------------- | ----- |
| **`transactions`** | `Transaction[]` | The current transactions for the user. | 0.1.0 |

#### GetProductByIdResult

| Prop          | Type      | Description          | Since |
| ------------- | --------- | -------------------- | ----- |
| **`product`** | `Product` | The product details. | 0.3.1 |

#### Product

Represents an in-app product available for purchase.

| Prop                      | Type                  | Description                                                                                                                                                                                                                                                              | Since  |
| ------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| **`id`**                  | `string`              | The unique product identifier.                                                                                                                                                                                                                                           | 0.3.1  |
| **`displayName`**         | `string`              | The localized display name of the product. On Android, this uses ProductDetails.getName(). On iOS, this uses [Product.displayName](#product).                                                                                                                            | 0.3.1  |
| **`description`**         | `string`              | The localized description of the product.                                                                                                                                                                                                                                | 0.3.1  |
| **`displayPrice`**        | `string`              | The localized price string, formatted for display.                                                                                                                                                                                                                       | 0.3.1  |
| **`price`**               | `number`              | The price as a decimal number. On Android, this is calculated from priceAmountMicros / 1,000,000. On iOS, this uses [Product.price](#product) as a decimal.                                                                                                              | 0.3.1  |
| **`currencyCode`**        | `string`              | The ISO 4217 currency code. On Android, this uses priceCurrencyCode. On iOS, this uses priceFormatStyle.currencyCode.                                                                                                                                                    | 0.3.1  |
| **`type`**                | `ProductType`         | The type of product.                                                                                                                                                                                                                                                     | 0.3.1  |
| **`pricingTerms`**        | `PricingTerms[]`      | The pricing terms available for the product, one entry per billing plan. Only present for auto-renewable subscriptions that are configured with multiple billing plans (e.g. monthly with 12-month commitment). Only available on iOS (26.4+).                           | 0.3.8  |
| **`subscriptionGroupId`** | `string`              | The identifier of the subscription group the product belongs to. Only present for auto-renewable subscriptions. Only available on iOS.                                                                                                                                   | 0.3.10 |
| **`subscriptionOffers`**  | `SubscriptionOffer[]` | The subscription offers available for the product. Only present for subscriptions. On **Android**, this contains one entry per base plan and offer combination. On **iOS**, this always contains exactly one entry, because every plan is configured as its own product. | 0.3.10 |

#### PricingTerms

The pricing terms for a billing plan of an auto-renewable subscription.

| Prop                 | Type                         | Description                                                                  | Since |
| -------------------- | ---------------------------- | ---------------------------------------------------------------------------- | ----- |
| **`planType`**       | `BillingPlanType`            | The plan type the pricing terms apply to.                                    | 0.3.8 |
| **`price`**          | `number`                     | The price billed per billing period, as a decimal number.                    | 0.3.8 |
| **`displayPrice`**   | `string`                     | The localized price string billed per billing period, formatted for display. | 0.3.8 |
| **`period`**         | `SubscriptionPeriod`         | The duration of one billing period.                                          | 0.3.8 |
| **`commitmentInfo`** | `PricingTermsCommitmentInfo` | The total commitment details that apply to this billing plan.                | 0.3.8 |

#### SubscriptionPeriod

A length of time for a subscription period.

| Prop        | Type                     | Description                        | Since |
| ----------- | ------------------------ | ---------------------------------- | ----- |
| **`value`** | `number`                 | The number of units in the period. | 0.3.8 |
| **`unit`**  | `SubscriptionPeriodUnit` | The unit of time for the period.   | 0.3.8 |

#### PricingTermsCommitmentInfo

The total commitment details of a billing plan.

| Prop               | Type                 | Description                                                        | Since |
| ------------------ | -------------------- | ------------------------------------------------------------------ | ----- |
| **`price`**        | `number`             | The total committed price, as a decimal number.                    | 0.3.8 |
| **`displayPrice`** | `string`             | The localized total committed price string, formatted for display. | 0.3.8 |
| **`period`**       | `SubscriptionPeriod` | The total commitment duration.                                     | 0.3.8 |

#### SubscriptionOffer

An offer to subscribe to a product.

| Prop               | Type                         | Description                                                                                                                                                                                            | Since  |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| **`basePlanId`**   | `string`                     | The ID of the base plan the offer belongs to. Only available on Android.                                                                                                                               | 0.3.10 |
| **`offerId`**      | `string`                     | The ID of the offer. Not present if the offer is the base plan itself. Only available on Android.                                                                                                      | 0.3.10 |
| **`tags`**         | `string[]`                   | The tags associated with the offer. Empty on iOS.                                                                                                                                                      | 0.3.10 |
| **`displayPrice`** | `string`                     | The localized recurring price string, formatted for display. This is the price the user pays after all introductory pricing phases have ended.                                                         | 0.3.10 |
| **`price`**        | `number`                     | The recurring price as a decimal number. This is the price the user pays after all introductory pricing phases have ended.                                                                             | 0.3.10 |
| **`currencyCode`** | `string`                     | The ISO 4217 currency code.                                                                                                                                                                            | 0.3.10 |
| **`period`**       | `SubscriptionPeriod`         | The duration of one recurring billing period.                                                                                                                                                          | 0.3.10 |
| **`phases`**       | `SubscriptionPricingPhase[]` | The pricing phases of the offer, in the order they are applied. The last phase is always the recurring phase. Any preceding phase is an introductory phase such as a free trial or a discounted price. | 0.3.10 |

#### SubscriptionPricingPhase

A pricing phase of a subscription offer.

| Prop                 | Type                         | Description                                                                                            | Since  |
| -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ | ------ |
| **`displayPrice`**   | `string`                     | The localized price string of the phase, formatted for display.                                        | 0.3.10 |
| **`price`**          | `number`                     | The price of the phase as a decimal number. This is `0` for a free trial.                              | 0.3.10 |
| **`currencyCode`**   | `string`                     | The ISO 4217 currency code.                                                                            | 0.3.10 |
| **`period`**         | `SubscriptionPeriod`         | The duration of one billing period of the phase.                                                       | 0.3.10 |
| **`cycleCount`**     | `number`                     | The number of billing periods the phase is applied for. This is `0` if the phase repeats indefinitely. | 0.3.10 |
| **`recurrenceMode`** | `PricingPhaseRecurrenceMode` | How the phase is repeated.                                                                             | 0.3.10 |

#### GetProductByIdOptions

| Prop                  | Type              | Description                                                                                                                                                                                              | Since |
| --------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`productCategory`** | `ProductCategory` | The category of product to fetch. If not specified, the plugin will query both categories. Only available on Android.                                                                                    | 0.3.3 |
| **`productId`**       | `string`          | The product ID of the product to retrieve. On Android, this is the [Product](#product) ID configured in Google Play Console. On iOS, this is the [Product](#product) ID configured in App Store Connect. | 0.3.1 |

#### GetProductsByIdsResult

| Prop           | Type        | Description                                                                                                                                                                        | Since |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`products`** | `Product[]` | The product details for the requested products. Note: If some products are not found, they will not be included in the array. The array may contain fewer products than requested. | 0.3.3 |

#### GetProductsByIdsOptions

| Prop                  | Type              | Description                                                                                                                                                                                                      | Since |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`productCategory`** | `ProductCategory` | The category of products to fetch. If not specified, the plugin will query both categories. Only available on Android.                                                                                           | 0.3.3 |
| **`productIds`**      | `string[]`        | The product IDs of the products to retrieve. On Android, these are the [Product](#product) IDs configured in Google Play Console. On iOS, these are the [Product](#product) IDs configured in App Store Connect. | 0.3.3 |

#### GetUnfinishedTransactionsResult

| Prop               | Type            | Description                               | Since |
| ------------------ | --------------- | ----------------------------------------- | ----- |
| **`transactions`** | `Transaction[]` | The unfinished transactions for the user. | 0.1.0 |

#### IsAvailableResult

| Prop              | Type      | Description                                                     | Since |
| ----------------- | --------- | --------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Indicates whether in-app purchases are available on the device. | 0.1.0 |

#### IsIntroOfferAvailableForProductResult

| Prop                        | Type      | Description                                                 | Since |
| --------------------------- | --------- | ----------------------------------------------------------- | ----- |
| **`isIntroOfferAvailable`** | `boolean` | Whether an introductory offer is available for the product. | 0.3.2 |

#### IsIntroOfferAvailableForProductOptions

| Prop            | Type     | Description                                  | Since |
| --------------- | -------- | -------------------------------------------- | ----- |
| **`productId`** | `string` | The product ID of the subscription to check. | 0.3.2 |

#### PurchaseProductResult

| Prop              | Type          | Description                                                   | Since |
| ----------------- | ------------- | ------------------------------------------------------------- | ----- |
| **`transaction`** | `Transaction` | The transaction that was created as a result of the purchase. | 0.1.0 |

#### PurchaseProductOptions

| Prop                      | Type              | Description                                                                                                                                                                                                                                                                             | Since |
| ------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`appAccountToken`**     | `string`          | A UUID string that associates the purchase with an account in your system. Apple returns it with the transaction, in the App Store Server API and in App Store Server Notifications. Generate a UUID per account instead of using a raw user identifier. Only available on iOS.         | 0.4.2 |
| **`basePlanId`**          | `string`          | The base plan ID of the subscription to purchase. Only available on Android.                                                                                                                                                                                                            | 0.3.5 |
| **`obfuscatedAccountId`** | `string`          | An obfuscated identifier that is uniquely associated with the user's account in your app. Google Play returns it with the purchase and in the Google Play Developer API. Use a one-way hash instead of a raw user identifier. Must not exceed 64 characters. Only available on Android. | 0.4.2 |
| **`obfuscatedProfileId`** | `string`          | An obfuscated identifier that is uniquely associated with the user's profile in your app, for apps where one account can hold several profiles. Use a one-way hash instead of a raw user identifier. Must not exceed 64 characters. Only available on Android.                          | 0.4.2 |
| **`offerId`**             | `string`          | The offer ID of the subscription offer to purchase. Only available on Android.                                                                                                                                                                                                          | 0.3.5 |
| **`planType`**            | `BillingPlanType` | The billing plan type to purchase for a monthly-with-12-month-commitment auto-renewable subscription. Only available on iOS (26.4+).                                                                                                                                                    | 0.3.8 |
| **`productId`**           | `string`          | The product ID of the product to purchase. On **Android**, this is the [Product](#product) ID configured in Google Play Console. On **iOS**, this is the [Product](#product) ID configured in App Store Connect.                                                                        | 0.1.0 |

### Enums

#### BillingPlanType

| Members       | Value        | Description                                                                     | Since |
| ------------- | ------------ | ------------------------------------------------------------------------------- | ----- |
| **`Monthly`** | `'MONTHLY'`  | The subscription is billed once per renewal period.                             | 0.3.8 |
| **`UpFront`** | `'UP_FRONT'` | The subscription is paid in full upfront at the start of the commitment period. | 0.3.8 |

#### ProductType

| Members                         | Value                           | Description                                                                                                                                                          | Since |
| ------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Consumable`**                | `'CONSUMABLE'`                  | A consumable in-app product. On Android, this is [ProductType](#producttype).INAPP. On iOS, this is [Product](#product).[ProductType](#producttype).consumable.      | 0.3.1 |
| **`NonConsumable`**             | `'NON_CONSUMABLE'`              | A non-consumable in-app product. On iOS, this is [Product](#product).[ProductType](#producttype).nonConsumable. Only available on iOS.                               | 0.3.1 |
| **`AutoRenewableSubscription`** | `'AUTO_RENEWABLE_SUBSCRIPTION'` | An auto-renewable subscription. On Android, this is [ProductType](#producttype).SUBS. On iOS, this is [Product](#product).[ProductType](#producttype).autoRenewable. | 0.3.1 |
| **`NonRenewableSubscription`**  | `'NON_RENEWABLE_SUBSCRIPTION'`  | A non-renewing subscription. On iOS, this is [Product](#product).[ProductType](#producttype).nonRenewable. Only available on iOS.                                    | 0.3.1 |

#### SubscriptionPeriodUnit

| Members       | Value       | Description                                                | Since |
| ------------- | ----------- | ---------------------------------------------------------- | ----- |
| **`Day`**     | `'DAY'`     |                                                            | 0.3.8 |
| **`Week`**    | `'WEEK'`    |                                                            | 0.3.8 |
| **`Month`**   | `'MONTH'`   |                                                            | 0.3.8 |
| **`Year`**    | `'YEAR'`    |                                                            | 0.3.8 |
| **`Unknown`** | `'UNKNOWN'` | The unit of time is not recognized by this plugin version. | 0.3.8 |

#### PricingPhaseRecurrenceMode

| Members                 | Value                  | Description                                                        | Since  |
| ----------------------- | ---------------------- | ------------------------------------------------------------------ | ------ |
| **`InfiniteRecurring`** | `'INFINITE_RECURRING'` | The phase repeats indefinitely until the subscription is canceled. | 0.3.10 |
| **`FiniteRecurring`**   | `'FINITE_RECURRING'`   | The phase repeats for a fixed number of billing periods.           | 0.3.10 |
| **`NonRecurring`**      | `'NON_RECURRING'`      | The phase is billed only once.                                     | 0.3.10 |

#### ProductCategory

| Members            | Value            | Description                                                                                                                               | Since |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`InApp`**        | `'IN_APP'`       | In-app products (consumables and non-consumables). On Android, this maps to `BillingClient.<a href="#producttype">ProductType</a>.INAPP`. | 0.3.3 |
| **`Subscription`** | `'SUBSCRIPTION'` | Subscription products. On Android, this maps to `BillingClient.<a href="#producttype">ProductType</a>.SUBS`.                              | 0.3.3 |

## Testing

### Android

To test in-app purchases on Android, you need to:

1. Upload your app to the Google Play Console (internal testing track is sufficient)
1. Add test accounts in Google Play Console under **Settings** → **License Testing**
1. Install the app from Google Play (not via direct APK installation)
1. Use test product IDs or enable license testing for your account

See [Test Google Play Billing](https://developer.android.com/google/play/billing/test) for more details.

### iOS

To test in-app purchases on iOS, you can use:

1. **Sandbox Testing**: Create sandbox test accounts in App Store Connect and test on physical devices or simulators
1. **StoreKit Testing in Xcode**: Configure a StoreKit configuration file for local testing without server connectivity (requires iOS 14+)

Sandbox accounts can be created in App Store Connect under **Users and Access** → **Sandbox**.

See [Testing In-App Purchases](https://developer.apple.com/documentation/storekit/in-app_purchase/testing_in-app_purchases) for more details.

## FAQ

### Do I need a third-party service to use this plugin?

No, the plugin uses the native store APIs directly, namely StoreKit 2 on iOS and the Google Play Billing Library on Android. For server-side validation, the plugin provides verification tokens (JWS on iOS, purchase tokens on Android) that you can pass to your own backend, and it includes transaction properties for third-party validation services if you prefer to use one.

### Why do I need to call `finishTransaction` after a purchase?

Calling `finishTransaction(...)` indicates to the store that your app has delivered the purchased content or enabled the service. Make sure to call it after every purchase, and check for unfinished transactions with `getUnfinishedTransactions()` at least once every app launch and whenever the app returns to the foreground. This ensures that all transactions are processed correctly, including pending purchases that were completed while the app was in the background.

### How do I validate purchases on my server?

Every transaction contains properties that you can pass to your server for validation. On iOS, use the `verificationResult` property, which contains the JWS representation of the transaction verification result. On Android, use the `token`, `originalJson`, and `signature` properties.

### Why does `syncTransactions` show a system dialog on iOS?

On iOS, calling `syncTransactions()` displays a system dialog asking the user to authenticate with their App Store credentials. You should therefore call this method only in response to an explicit user action, for example a "Restore Purchases" button. On Android, this method silently queries and refreshes purchases from Google Play without user interaction.

### Which iOS versions are supported?

Most methods require iOS 15.0 or later because the plugin uses StoreKit 2. Billing plan features, such as monthly-with-12-month-commitment subscriptions, require iOS 26.4 or later. Additionally, Xcode 26.5 or later is required to build the plugin, as mentioned in the [Prerequisites](#prerequisites) section.

### How do I test in-app purchases?

On Android, upload your app to the Google Play Console, add test accounts under License Testing, and install the app from Google Play. On iOS, use sandbox test accounts created in App Store Connect or a StoreKit configuration file in Xcode. See the [Testing](#testing) section for detailed instructions.

## Related Plugins

- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/): Allow users to submit app store reviews and ratings.
- [Square Mobile Payments](https://capawesome.io/docs/sdks/capacitor/square-mobile-payments/): Unofficial Capacitor plugin for the Square Mobile Payments SDK.
- [Superwall](https://capawesome.io/docs/sdks/capacitor/superwall/): Unofficial Capacitor plugin for the Superwall SDK to present remotely configured paywalls.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/purchases/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/purchases/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/purchases/LICENSE).

## Third-Party Notices

This plugin depends on the **Google Play Billing Library** (`com.android.billingclient:billing`), governed by the [Android Software Development Kit License Agreement](https://developer.android.com/studio/terms). The library is not bundled in this plugin; it is fetched at build time from Google's Maven repository by your application's build system. By building an Android application that uses this plugin, you accept the Android SDK License Agreement and the [Google Play Developer Program Policies](https://play.google.com/about/developer-content-policy/), and you are responsible for ensuring your app complies with both. This plugin is intended for use in applications distributed via the Google Play Store on compatible Android devices. "Google Play", "Google Play Billing", and "Google Play Store" are used as descriptive identifiers only — no affiliation with or endorsement by Google is claimed or implied.

# Capacitor RealtimeKit Plugin

Unofficial Capacitor plugin for using the [RealtimeKit SDK](https://docs.realtime.cloudflare.com/).[1](#fn:1)

## Use Cases

The RealtimeKit plugin is typically used to add real-time meetings to an app, for example:

- **Video meetings**: Start a meeting with the built-in meeting UI without building your own interface.
- **Audio-only calls**: Join meetings with video disabled for voice-only communication.
- **Telehealth and remote support**: Let patients or customers join video sessions authenticated with a participant token.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.2.x          | >=8.x.x           | Active support |
| 0.1.x          | 7.x.x             | Deprecated     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-realtimekit` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-realtimekit
npx cap sync
```

### Android

This plugin is supported on Android SDK +24.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$realtimekitUiVersion` version of `com.cloudflare.realtimekit:ui-android` (default: `0.3.1`)

### iOS

#### Privacy Descriptions

Add the following keys to the `ios/App/App/Info.plist` file:

```
<key>NSBluetoothPeripheralUsageDescription</key>
<string>We will use your Bluetooth to access your Bluetooth headphones.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>We will use your Bluetooth to access your Bluetooth headphones.</string>
<key>NSCameraUsageDescription</key>
<string>For people to see you during meetings, we need access to your camera.</string>
<key>NSMicrophoneUsageDescription</key>
<string>For people to hear you during meetings, we need access to your microphone.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>For people to share, we need access to your photos.</string>
<key>UIBackgroundModes</key>
    <array>
        <string>audio</string>
        <string>voip</string>
        <string>fetch</string>
        <string>remote-notification</string>
    </array>
```

## Usage

The following examples show how to initialize the plugin and start a meeting.

### Initialize the plugin

Call `initialize()` before using any other method of the plugin:

```
import { RealtimeKit } from '@capawesome/capacitor-realtimekit';

const initialize = async () => {
  await RealtimeKit.initialize();
};
```

### Start a meeting

Start a meeting using the built-in UI. The options let you pass the participant's authentication token and control whether the participant joins with audio and video enabled. Only available on Android and iOS:

```
import { RealtimeKit, StartMeetingOptions } from '@capawesome/capacitor-realtimekit';

const startMeeting = async (options: StartMeetingOptions) => {
  await RealtimeKit.startMeeting(options);
};
```

## API

- [`initialize()`](#initialize)
- [`startMeeting(...)`](#startmeeting)
- [Interfaces](#interfaces)

### initialize()

```
initialize() => Promise<void>
```

Initialize the RealtimeKit plugin.

This method must be called before using any other methods in the plugin.

**Since:** 0.0.0

______________________________________________________________________

### startMeeting(...)

```
startMeeting(options: StartMeetingOptions) => Promise<void>
```

Start a meeting using the built-in UI.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `StartMeetingOptions` |

**Since:** 0.0.0

______________________________________________________________________

### Interfaces

#### StartMeetingOptions

| Prop              | Type      | Description                                     | Default | Since |
| ----------------- | --------- | ----------------------------------------------- | ------- | ----- |
| **`authToken`**   | `string`  | The authentication token for the participant.   |         | 0.0.0 |
| **`enableAudio`** | `boolean` | Whether to join the meeting with audio enabled. | `true`  | 0.0.0 |
| **`enableVideo`** | `boolean` | Whether to join the meeting with video enabled. | `true`  | 0.0.0 |

## FAQ

### Do I have to call the `initialize` method before starting a meeting?

Yes, the `initialize()` method must be called before using any other method of the plugin, including `startMeeting(...)`.

### Can participants join a meeting without camera or microphone?

Yes, set the `enableAudio` or `enableVideo` option of the `startMeeting(...)` method to `false` to join the meeting with the microphone or camera disabled. Both options default to `true`.

### Does this plugin work on the Web?

No, the `startMeeting(...)` method is only available on Android and iOS, since it relies on the native RealtimeKit SDK and its built-in meeting UI.

### What do I need to configure on iOS?

You must add privacy descriptions for Bluetooth, camera, microphone, and photo library access as well as the required background modes to your `Info.plist` file. See the [Installation](#installation) section for the exact keys.

### Which Android versions are supported?

The plugin is supported on Android SDK 24 and newer. It also uses the `$realtimekitUiVersion` project variable to control the version of the `com.cloudflare.realtimekit:ui-android` dependency.

### Is this an official Cloudflare plugin?

No, this is an unofficial plugin. The project is not affiliated with, endorsed by, sponsored by, or approved by Cloudflare, Inc. or any of their affiliates or subsidiaries.

## Related Plugins

- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session.
- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/): Transcribe speech into text with advanced features like silence detection.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Cloudflare, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Root Detection Plugin

Capacitor plugin for detecting rooted and jailbroken devices.

## Features

- 🔒 **Root detection**: Detect rooted (Android) and jailbroken (iOS) devices.
- 🤖 **Emulator detection**: Detect whether the app is running on an emulator or simulator.
- 🛠️ **Developer mode**: Detect whether developer mode is enabled (Android).
- 🤝 **Compatibility**: Works alongside the [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/) plugin for server-verifiable device attestation.
- 📦 **SPM**: Supports Swift Package Manager and CocoaPods for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Root Detection plugin is typically used in apps that handle sensitive data and need to assess the trustworthiness of the device, for example:

- **Banking and fintech apps**: Warn users or restrict access when the app runs on a rooted or jailbroken device.
- **Fraud prevention**: Detect emulators and simulators to make automated abuse of your app harder.
- **Compliance checks**: Detect whether developer mode is enabled on Android to satisfy internal security policies.
- **Conditional feature gating**: Disable particularly sensitive features on compromised devices while keeping the rest of the app usable.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-root-detection` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-root-detection
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$rootbeerVersion` version of `com.scottyab:rootbeer-lib` (default: `0.1.2`)

### iOS

#### Application Queries Schemes

The `isRooted()` method checks whether the `cydia://` URL scheme can be opened as part of its jailbreak heuristics. For this check to work, add the `cydia` scheme to the `LSApplicationQueriesSchemes` array in the `Info.plist` file of your app:

```
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>cydia</string>
</array>
```

This step is optional. If the scheme is not added, the `isRooted()` method still works but skips the URL scheme check.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the device is rooted or jailbroken, running on an emulator, or has developer mode enabled.

### Check whether the device is rooted or jailbroken

Check whether the device is rooted (Android) or jailbroken (iOS). Keep in mind that this is a best-effort, client-side check that can be bypassed by a determined attacker (see [Security Considerations](#security-considerations)):

```
import { RootDetection } from '@capawesome/capacitor-root-detection';

const isRooted = async () => {
  const { rooted } = await RootDetection.isRooted();
  return rooted;
};
```

### Check whether the app runs on an emulator

Check whether the app is running on an emulator (Android) or simulator (iOS):

```
import { RootDetection } from '@capawesome/capacitor-root-detection';

const isEmulator = async () => {
  const { emulator } = await RootDetection.isEmulator();
  return emulator;
};
```

### Check whether developer mode is enabled

Check whether developer mode is enabled on the device. Only available on Android:

```
import { RootDetection } from '@capawesome/capacitor-root-detection';

const isDeveloperModeEnabled = async () => {
  const { enabled } = await RootDetection.isDeveloperModeEnabled();
  return enabled;
};
```

## API

- [`isDeveloperModeEnabled()`](#isdevelopermodeenabled)
- [`isEmulator()`](#isemulator)
- [`isRooted()`](#isrooted)
- [Interfaces](#interfaces)

### isDeveloperModeEnabled()

```
isDeveloperModeEnabled() => Promise<IsDeveloperModeEnabledResult>
```

Check whether developer mode is enabled on the device.

Only available on Android.

**Returns:** `Promise<IsDeveloperModeEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### isEmulator()

```
isEmulator() => Promise<IsEmulatorResult>
```

Check whether the app is running on an emulator (Android) or simulator (iOS).

**Returns:** `Promise<IsEmulatorResult>`

**Since:** 0.1.0

______________________________________________________________________

### isRooted()

```
isRooted() => Promise<IsRootedResult>
```

Check whether the device is rooted (Android) or jailbroken (iOS).

**Attention**: This is a best-effort, client-side check that can be bypassed by a determined attacker. Do not rely on it as the sole security measure. Use the App Integrity plugin when server-verifiable trust is required.

**Returns:** `Promise<IsRootedResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IsDeveloperModeEnabledResult

| Prop          | Type      | Description                                      | Since |
| ------------- | --------- | ------------------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether developer mode is enabled on the device. | 0.1.0 |

#### IsEmulatorResult

| Prop           | Type      | Description                                                             | Since |
| -------------- | --------- | ----------------------------------------------------------------------- | ----- |
| **`emulator`** | `boolean` | Whether the app is running on an emulator (Android) or simulator (iOS). | 0.1.0 |

#### IsRootedResult

| Prop         | Type      | Description                                                 | Since |
| ------------ | --------- | ----------------------------------------------------------- | ----- |
| **`rooted`** | `boolean` | Whether the device is rooted (Android) or jailbroken (iOS). | 0.1.0 |

## Security Considerations

The checks provided by this plugin are performed entirely on the device and are **best-effort**. A determined attacker with full control over a rooted or jailbroken device can bypass or spoof any client-side detection. Therefore, you should **never** rely on this plugin as the sole security measure for protecting sensitive functionality.

For **server-verifiable** device and app integrity, use the [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/) plugin, which leverages the Play Integrity API (Android) and App Attest (iOS) to produce attestations that can be validated on your backend.

## FAQ

### How is this plugin different from other similar plugins?

It combines several device-trust signals in one fully typed API: root and jailbreak detection on Android and iOS, emulator and simulator detection, and a developer-mode check on Android. These are fast, client-side checks that are easy to drop into any app, and the plugin is designed to work alongside the App Integrity plugin when you also need server-verifiable attestation. If a lightweight client-side signal is all you need, this covers it well; when you need a full trust story, the two plugins fit together.

### Can root detection be bypassed?

Yes. All checks provided by this plugin are performed entirely on the device and are best-effort. A determined attacker with full control over a rooted or jailbroken device can bypass or spoof any client-side detection. You should therefore never rely on this plugin as the sole security measure. See the [Security Considerations](#security-considerations) section for details.

### What is the difference between this plugin and the App Integrity plugin?

The Root Detection plugin performs client-side checks that run entirely on the device, which makes them fast and easy to use but also spoofable. The [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/) plugin leverages the Play Integrity API (Android) and App Attest (iOS) to produce attestations that can be validated on your backend, providing server-verifiable trust. The two plugins are designed to work alongside each other.

### Which methods are available on which platforms?

The `isRooted()` and `isEmulator()` methods are available on Android and iOS. The `isDeveloperModeEnabled()` method is only available on Android. There is no Web implementation, since rooting and jailbreaking are concepts of mobile operating systems.

### Do I need any special configuration on iOS?

Optionally, you can add the `cydia` scheme to the `LSApplicationQueriesSchemes` array in your app's `Info.plist` file so that the `isRooted()` method can check whether the `cydia://` URL scheme can be opened as part of its jailbreak heuristics. If the scheme is not added, the method still works but skips the URL scheme check. See the [Installation](#installation) section for details.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/): Verify app and device integrity using the Play Integrity API (Android) and App Attest (iOS).
- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition.
- [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/): Hide sensitive app content in the app switcher, block screenshots, and detect when a screenshot is taken.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/root-detection/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/root-detection/LICENSE).

# Capacitor Screen Brightness Plugin

Capacitor plugin for reading and controlling the screen brightness.

## Features

- ☀️ **Read brightness**: Read the current screen brightness.
- 🔆 **Set brightness**: Set the screen brightness, e.g. to boost it for barcode or ticket display.
- 🔄 **Reset brightness**: Hand the brightness control back to the operating system.
- 🤝 **Compatibility**: Works alongside the [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/) and [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Screen Brightness plugin is typically used whenever an app needs to take control of the display brightness, for example:

- **Barcode and QR code display**: Boost the brightness to maximum so scanners can reliably read tickets, boarding passes, or loyalty cards.
- **Reading and media apps**: Dim the screen for a more comfortable viewing experience in dark environments.
- **Brightness-aware features**: Read the current brightness to adapt your UI or restore it later.
- **Kiosk and point-of-sale apps**: Keep the display at a defined brightness level while the app is in use and hand control back to the operating system afterwards.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-screen-brightness` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-screen-brightness
npx cap sync
```

This plugin is available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get, set, and reset the screen brightness.

### Get the current screen brightness

Read the current screen brightness as a value between `0.0` (darkest) and `1.0` (brightest):

```
import { ScreenBrightness } from '@capawesome/capacitor-screen-brightness';

const getBrightness = async () => {
  const { brightness } = await ScreenBrightness.getBrightness();
  return brightness;
};
```

### Set the screen brightness

Set the screen brightness to a value between `0.0` (darkest) and `1.0` (brightest). On Android, only the brightness of the current app window is changed and the change is reverted automatically as soon as the app is closed. On iOS, this changes the system brightness and the change persists after the app is closed:

```
import { ScreenBrightness } from '@capawesome/capacitor-screen-brightness';

const setBrightness = async () => {
  await ScreenBrightness.setBrightness({ brightness: 1 });
};
```

### Reset the screen brightness

Hand the brightness control back to the operating system. Only available on Android:

```
import { ScreenBrightness } from '@capawesome/capacitor-screen-brightness';

const resetBrightness = async () => {
  await ScreenBrightness.resetBrightness();
};
```

## API

- [`getBrightness()`](#getbrightness)
- [`resetBrightness()`](#resetbrightness)
- [`setBrightness(...)`](#setbrightness)
- [Interfaces](#interfaces)

### getBrightness()

```
getBrightness() => Promise<GetBrightnessResult>
```

Get the current screen brightness.

Only available on Android and iOS.

**Returns:** `Promise<GetBrightnessResult>`

**Since:** 0.1.0

______________________________________________________________________

### resetBrightness()

```
resetBrightness() => Promise<void>
```

Reset the screen brightness to the system default.

This hands the brightness control back to the operating system.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### setBrightness(...)

```
setBrightness(options: SetBrightnessOptions) => Promise<void>
```

Set the screen brightness.

On Android, only the brightness of the current app window is changed. The change is reverted automatically as soon as the app is closed.

On iOS, this changes the **system** brightness and the change persists after the app is closed.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetBrightnessOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetBrightnessResult

| Prop             | Type     | Description                                                                             | Since |
| ---------------- | -------- | --------------------------------------------------------------------------------------- | ----- |
| **`brightness`** | `number` | The current screen brightness as a value between `0.0` (darkest) and `1.0` (brightest). | 0.1.0 |

#### SetBrightnessOptions

| Prop             | Type     | Description                                                                            | Since |
| ---------------- | -------- | -------------------------------------------------------------------------------------- | ----- |
| **`brightness`** | `number` | The screen brightness to set as a value between `0.0` (darkest) and `1.0` (brightest). | 0.1.0 |

## Platform Notes

### Android

Setting the brightness only affects the **current app window** and does not require the `WRITE_SETTINGS` permission. The change is reverted automatically as soon as the app is closed. Use `resetBrightness()` to hand the brightness control back to the operating system while the app is running.

### iOS

Setting the brightness changes the **system** brightness and the change **persists** after the app is closed. There is no system API to hand the brightness control back to the operating system, so `resetBrightness()` is not available on iOS and rejects as unimplemented.

## FAQ

### How is this plugin different from other similar plugins?

It reads, sets, and (on Android) resets the screen brightness through a small, fully typed API, using a normalized `0.0`–`1.0` range on both platforms. On Android it changes only the current app window, so no `WRITE_SETTINGS` permission is required and the change reverts automatically when the app closes, which makes use cases like boosting brightness to display a barcode or ticket straightforward. It supports CocoaPods and Swift Package Manager on iOS and is actively maintained against the latest Capacitor version.

### Why does the brightness stay changed after closing my app on iOS?

On iOS, setting the brightness changes the system brightness, which persists after the app is closed. There is no system API to hand the brightness control back to the operating system on iOS. If you want to be a good citizen, read the current brightness with `getBrightness()` before changing it and restore that value when your app goes to the background.

### Why is the resetBrightness method not available on iOS?

The `resetBrightness()` method hands the brightness control back to the operating system, which is only possible on Android. On iOS, there is no system API for this, so the method rejects as unimplemented. See the [Platform Notes](#platform-notes) section for details.

### Does setting the brightness require any permissions on Android?

No. On Android, the plugin only changes the brightness of the current app window, which does not require the `WRITE_SETTINGS` permission. The change is reverted automatically as soon as the app is closed.

### What values can I use for the brightness?

The brightness is a number between `0.0` (darkest) and `1.0` (brightest). The same range is used by `getBrightness()` when reading the current brightness.

### Does this plugin work on the Web?

No. The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented, since browsers do not provide an API to control the screen brightness.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake while your app is in use.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation.
- [Torch](https://capawesome.io/docs/sdks/capacitor/torch/): Switch the flashlight on and off.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-brightness/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-brightness/LICENSE).

# Capacitor Screen Orientation Plugin

Capacitor plugin to lock/unlock the screen orientation.

## Features

The Capacitor Screen Orientation plugin is one of the most complete orientation control solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🔒 **Orientation locking**: Lock screen to specific orientations.
- 🔓 **Orientation unlocking**: Unlock and restore automatic orientation.
- 📱 **Multiple orientations**: Support for portrait, landscape, and specific orientations.
- 🔄 **Orientation detection**: Get current screen orientation.
- 📢 **Event listeners**: Listen to orientation change events.
- 📐 **Fine-grained control**: Primary and secondary orientation modes.
- 🍎 **iPad support**: Special configuration for iPad orientation locking.
- 🤝 **Compatibility**: Works alongside the [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/), [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/) and [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Screen Orientation plugin is typically used whenever certain screens of an app only work well in a specific orientation, for example:

- **Video players**: Lock the screen to landscape for fullscreen video playback.
- **Games**: Keep the game in a fixed orientation regardless of how the device is held.
- **Camera and scanner screens**: Lock the screen to portrait while capturing photos or scanning codes.
- **Forms and reading views**: Prevent accidental rotation while the user is typing or reading.
- **Responsive layouts**: React to orientation changes with the `screenOrientationChange` event to adapt your UI.

## 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     |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-screen-orientation` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-screen-orientation
npx cap sync
```

### iOS

#### General

On iOS you must add the following to your app's `AppDelegate.swift`:

```
+ import ScreenOrientationPlugin

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

+ func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
+   return ScreenOrientation.getSupportedInterfaceOrientations()
+ }
```

If your project still uses CocoaPods instead of Swift Package Manager (SPM), import `CapawesomeCapacitorScreenOrientation` rather than `ScreenOrientationPlugin`:

```
+ import CapawesomeCapacitorScreenOrientation
```

#### iPad Orientation Lock

On iPad, you must add the following to your app's `Info.plist`:

```
<key>UIRequiresFullScreen</key>
<true/>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to lock, unlock, and read the current screen orientation.

### Lock the screen orientation

Lock the device to a specific orientation, for example landscape. Besides `LANDSCAPE` and `PORTRAIT`, you can also lock to a primary or secondary mode such as `LANDSCAPE_PRIMARY` for fine-grained control:

```
import { ScreenOrientation, OrientationType } from '@capawesome/capacitor-screen-orientation';

const lock = async () => {
  await ScreenOrientation.lock({ type: OrientationType.LANDSCAPE });
};
```

### Unlock the screen orientation

Remove the orientation lock and restore automatic rotation:

```
import { ScreenOrientation } from '@capawesome/capacitor-screen-orientation';

const unlock = async () => {
  await ScreenOrientation.unlock();
};
```

### Get the current screen orientation

Read the current orientation type of the device:

```
import { ScreenOrientation } from '@capawesome/capacitor-screen-orientation';

const getCurrentOrientation = async () => {
  const result = await ScreenOrientation.getCurrentOrientation();
  return result.type;
};
```

## API

- [`lock(...)`](#lock)
- [`unlock()`](#unlock)
- [`getCurrentOrientation()`](#getcurrentorientation)
- [`addListener('screenOrientationChange', ...)`](#addlistenerscreenorientationchange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### lock(...)

```
lock(options?: LockOptions | undefined) => Promise<void>
```

Locks the device orientation.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `LockOptions` |

______________________________________________________________________

### unlock()

```
unlock() => Promise<void>
```

Unlocks the device orientation.

______________________________________________________________________

### getCurrentOrientation()

```
getCurrentOrientation() => Promise<GetCurrentOrientationResult>
```

Gets the current device orientation type.

**Returns:** `Promise<GetCurrentOrientationResult>`

______________________________________________________________________

### addListener('screenOrientationChange', ...)

```
addListener(eventName: 'screenOrientationChange', listenerFunc: ScreenOrientationChangeListener) => Promise<PluginListenerHandle>
```

Listen for screen orientation changes.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'screenOrientationChange'`       |
| **`listenerFunc`** | `ScreenOrientationChangeListener` |

**Returns:** `Promise<PluginListenerHandle>`

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

______________________________________________________________________

### Interfaces

#### LockOptions

| Prop       | Type              | Description                |
| ---------- | ----------------- | -------------------------- |
| **`type`** | `OrientationType` | The orientation lock type. |

#### GetCurrentOrientationResult

| Prop       | Type              | Description                   |
| ---------- | ----------------- | ----------------------------- |
| **`type`** | `OrientationType` | The current orientation type. |

#### PluginListenerHandle

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

#### ScreenOrientationChange

| Prop       | Type              | Description                   |
| ---------- | ----------------- | ----------------------------- |
| **`type`** | `OrientationType` | The current orientation type. |

### Type Aliases

#### ScreenOrientationChangeListener

Callback to receive the screen orientation change notifications.

`(change: ScreenOrientationChange): void`

### Enums

#### OrientationType

| Members                   | Value                   | Description                                                         |
| ------------------------- | ----------------------- | ------------------------------------------------------------------- |
| **`LANDSCAPE`**           | `'landscape'`           | The orientation is either landscape-primary or landscape-secondary. |
| **`LANDSCAPE_PRIMARY`**   | `'landscape-primary'`   | The orientation is in the primary landscape mode.                   |
| **`LANDSCAPE_SECONDARY`** | `'landscape-secondary'` | The orientation is in the secondary landscape mode.                 |
| **`PORTRAIT`**            | `'portrait'`            | The orientation is either portrait-primary or portrait-secondary.   |
| **`PORTRAIT_PRIMARY`**    | `'portrait-primary'`    | The orientation is in the primary portrait mode.                    |
| **`PORTRAIT_SECONDARY`**  | `'portrait-secondary'`  | The orientation is in the secondary portrait mode.                  |

## FAQ

### Why does the orientation lock not work on iPad?

For the orientation lock to work on iPad, you must add the `UIRequiresFullScreen` key with the value `true` to your app's `Info.plist` file, as described in the [Installation](#installation) section. Also make sure that you have applied the required changes to your `AppDelegate.swift`.

### Do I need to modify my AppDelegate on iOS?

Yes. You must implement the `supportedInterfaceOrientationsFor` method in your app's `AppDelegate.swift` and return `ScreenOrientation.getSupportedInterfaceOrientations()`, as shown in the [Installation](#installation) section. Without this change, the orientation lock has no effect on iOS.

### What is the difference between LANDSCAPE and LANDSCAPE_PRIMARY?

The `LANDSCAPE` type covers both landscape modes, so the device can be rotated between landscape-primary and landscape-secondary while locked. The `LANDSCAPE_PRIMARY` and `LANDSCAPE_SECONDARY` types lock the screen to exactly one of the two landscape modes. The same applies to `PORTRAIT`, `PORTRAIT_PRIMARY` and `PORTRAIT_SECONDARY`.

### How do I restore automatic rotation after locking the orientation?

Simply call the `unlock()` method. It removes the orientation lock so that the device rotates automatically again based on the user's device settings.

### How can I react to orientation changes?

Add a listener for the `screenOrientationChange` event using the `addListener(...)` method. The listener receives the new orientation type every time the screen orientation changes. Use `removeAllListeners()` to remove all listeners when you no longer need them.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/): Hide and show the iOS home indicator.
- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake, for example during video playback.
- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/): Set the background color and button style of the Android navigation bar.
- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/): Read and control the screen brightness.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-orientation/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-orientation/LICENSE).

## Credits

This plugin is based on the [Capacitor Screen Orientation](https://github.com/capawesome-team/capacitor-screen-orientation) plugin. Thanks to everyone who contributed to the project!

# Capacitor Screen Reader Plugin

Capacitor plugin to interact with screen readers.

## Features

- 🔎 **Detection**: Check whether a screen reader (VoiceOver/TalkBack) is currently enabled.
- 📣 **Announcements**: Post accessibility announcements that are read out by the active screen reader.
- 🔔 **State changes**: Listen for changes to the enabled state of the screen reader.
- 🖥️ **Cross-platform**: Supports Android, iOS and the web.
- 🤝 **Compatibility**: Works alongside the [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

> [!NOTE] This plugin does **not** perform text-to-speech. The `announce(...)` method posts an accessibility announcement that is only read out when a screen reader is active. If you are looking for real text-to-speech, use the [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugin instead.

## Use Cases

The Screen Reader plugin is typically used to make apps more accessible for users of VoiceOver and TalkBack, for example:

- **Accessible status updates**: Announce dynamic changes such as "The item was added to your cart." that would otherwise go unnoticed by screen reader users.
- **Adaptive user interfaces**: Check whether a screen reader is enabled and adapt your UI accordingly, for example by simplifying gestures or animations.
- **Reacting to state changes**: Listen for changes to the enabled state of the screen reader and adjust your app's behavior on the fly.
- **Localized announcements**: Provide the language of an announcement on Android so the screen reader pronounces it correctly.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-screen-reader` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-screen-reader
npx cap sync
```

### Android

No additional configuration is required for this plugin.

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to post an accessibility announcement, check whether a screen reader is enabled, and listen for screen reader state changes.

### Post an accessibility announcement

Post an announcement that is read out by the active screen reader (VoiceOver/TalkBack). Note that this does not perform text-to-speech; the message is only read out if a screen reader is running:

```
import { ScreenReader } from '@capawesome/capacitor-screen-reader';

const announce = async () => {
  await ScreenReader.announce({
    value: 'The item was added to your cart.',
  });
};
```

### Check whether a screen reader is enabled

Check whether a screen reader is currently enabled. Only available on Android and iOS:

```
import { ScreenReader } from '@capawesome/capacitor-screen-reader';

const isEnabled = async () => {
  const { enabled } = await ScreenReader.isEnabled();
  return enabled;
};
```

### Listen for screen reader state changes

Get notified when the screen reader is enabled or disabled. Only available on Android and iOS:

```
import { ScreenReader } from '@capawesome/capacitor-screen-reader';

const addStateChangeListener = async () => {
  await ScreenReader.addListener('stateChange', event => {
    console.log('Screen reader enabled:', event.enabled);
  });
};

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

## API

- [`announce(...)`](#announce)
- [`isEnabled()`](#isenabled)
- [`addListener('stateChange', ...)`](#addlistenerstatechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### announce(...)

```
announce(options: AnnounceOptions) => Promise<void>
```

Post an accessibility announcement to the active screen reader.

This does **not** perform text-to-speech. It posts an announcement that is read out by the screen reader (VoiceOver/TalkBack) if one is active. For real text-to-speech, use the [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugin instead.

On the web, the announcement is made through a visually hidden `aria-live` region, so it is only read out if the user has a screen reader running.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `AnnounceOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Check whether a screen reader is currently enabled.

On Android, this refers to whether touch exploration (TalkBack) is enabled. On iOS, this refers to whether VoiceOver is running.

Only available on Android and iOS.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('stateChange', ...)

```
addListener(eventName: 'stateChange', listenerFunc: (event: StateChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the enabled state of the screen reader.

The device is only observed while at least one listener is attached.

Only available on Android and iOS.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'stateChange'`                     |
| **`listenerFunc`** | `(event: StateChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AnnounceOptions

| Prop           | Type     | Description                                                                                                                                    | Since |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`value`**    | `string` | The message to announce.                                                                                                                       | 0.1.0 |
| **`language`** | `string` | The language of the message as a BCP 47 language tag. This helps the screen reader pronounce the message correctly. Only available on Android. | 0.1.0 |

#### IsEnabledResult

| Prop          | Type      | Description                                   | Since |
| ------------- | --------- | --------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether a screen reader is currently enabled. | 0.1.0 |

#### PluginListenerHandle

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

#### StateChangeEvent

| Prop          | Type      | Description                                   | Since |
| ------------- | --------- | --------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether a screen reader is currently enabled. | 0.1.0 |

## Migrating from `@capacitor/screen-reader`

This plugin is a drop-in replacement for the official `@capacitor/screen-reader` plugin with a few naming changes:

| `@capacitor/screen-reader`        | Screen Reader                     |
| --------------------------------- | --------------------------------- |
| `speak({ value, language })`      | `announce({ value, language })`   |
| `isEnabled()`                     | `isEnabled()`                     |
| `addListener('stateChange', ...)` | `addListener('stateChange', ...)` |

The `speak(...)` method has been renamed to `announce(...)` to make it clear that it posts an accessibility announcement to the active screen reader and does **not** perform text-to-speech. For real text-to-speech, use the [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugin instead.

## FAQ

### How is this plugin different from other similar plugins?

It focuses on real accessibility work with VoiceOver and TalkBack: you can post announcements, check whether a screen reader is enabled, and listen for state changes, with the device observed only while a listener is attached. Announcements work on Android, iOS, and the web, where they use a visually hidden `aria-live` region, and on Android you can provide the announcement language so it is pronounced correctly. The API is fully typed, is actively maintained against the latest Capacitor version, and pairs naturally with the Accessibility Preferences and Speech Synthesis plugins for a complete accessibility toolkit.

### Does the announce method perform text-to-speech?

No. The `announce(...)` method posts an accessibility announcement that is only read out by the screen reader (VoiceOver/TalkBack) if one is active. If you are looking for real text-to-speech that always speaks, use the [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugin instead.

### Why is my announcement not read out?

Announcements are only read out when a screen reader is active. On Android and iOS, make sure TalkBack or VoiceOver is enabled. On the Web, the announcement is made through a visually hidden `aria-live` region, so it is only read out if the user has a screen reader running.

### Can I check whether a screen reader is enabled on the Web?

No. The `isEnabled()` method and the `stateChange` listener are only available on Android and iOS. Browsers do not expose whether a screen reader is running. The `announce(...)` method, however, also works on the Web via an `aria-live` region.

### How is this plugin different from the official @capacitor/screen-reader plugin?

This plugin is a drop-in replacement for the official `@capacitor/screen-reader` plugin with a few naming changes. Most notably, the `speak(...)` method has been renamed to `announce(...)` to make it clear that it posts an accessibility announcement and does not perform text-to-speech. See the [migration guide](#migrating-from-capacitorscreen-reader) above for a complete mapping.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/): Read the user's system accessibility preferences.
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text (text-to-speech) with voice selection, pitch, and rate control.
- [Text Zoom](https://capawesome.io/docs/sdks/capacitor/text-zoom/): Read and control the WebView text zoom.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-reader/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-reader/LICENSE).

# Capacitor Screenshot Plugin

Capacitor plugin for taking screenshots.

## Features

The Capacitor Screenshot plugin is one of the most capable screen capture solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 📸 **Easy screenshots**: Simple one-method API for taking screenshots.
- 🌐 **Web support**: Uses html2canvas for web platform screenshot capture.
- 📱 **Native capture**: High-quality native screenshot capture on mobile.
- 🤝 **Compatibility**: Works alongside the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/), [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/) and [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Screenshot plugin is typically used whenever an app needs to capture its own screen, for example:

- **Bug reporting and feedback**: Attach a screenshot of the current screen to bug reports or feedback forms.
- **Sharing app content**: Capture achievements, results, or other screens so users can share them.
- **Support tickets**: Capture the current state of the app to help your support team reproduce issues.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-screenshot` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-screenshot html2canvas
npx cap sync
```

## Usage

The following example shows how to take a screenshot of the current screen.

### Take a screenshot

Take a screenshot of the current screen. The result contains the file path of the screenshot on Android and iOS, or a data URI on the Web:

```
import { Screenshot } from '@capawesome/capacitor-screenshot';

const take = async () => {
  const { uri } = await Screenshot.take();
  console.log('Screenshot saved at:', uri);
};
```

## API

- [`take()`](#take)
- [Interfaces](#interfaces)

### take()

```
take() => Promise<TakeResult>
```

Take a screenshot.

**Returns:** `Promise<TakeResult>`

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### TakeResult

| Prop      | Type     | Description                                                          | Since |
| --------- | -------- | -------------------------------------------------------------------- | ----- |
| **`uri`** | `string` | The file path (Android and iOS) or data URI (Web) of the screenshot. | 6.0.0 |

## FAQ

### What does the take method return on each platform?

On Android and iOS, the `take()` method returns the file path of the captured screenshot. On the Web, it returns a data URI instead, since the screenshot is rendered with `html2canvas` in the browser.

### Why do I need to install html2canvas?

The `html2canvas` package is only required if you use the plugin on the Web platform, where it is used to render the screenshot. On Android and iOS, the screenshot is captured natively and `html2canvas` is not needed. See the [Installation](#installation) section for details.

### Can I prevent screenshots of my app?

No, this plugin only takes screenshots. If you want to block screenshots, hide sensitive app content in the app switcher, or detect when a screenshot is taken, use the [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/) plugin instead.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application.
- [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/): Let the user edit a photo, for example a captured screenshot.
- [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/): Hide sensitive app content in the app switcher, block screenshots, and detect when a screenshot is taken.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screenshot/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screenshot/LICENSE).

# Capacitor Secure Preferences Plugin

Capacitor plugin to securely store key/value pairs such as tokens, API keys or other app-managed secrets.

## Features

The Capacitor Secure Preferences plugin is one of the most complete secure storage solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Native secure storage on Android and iOS, with a `localStorage`-backed web implementation for development.
- 🔒 **Secure**: Store sensitive information such as tokens securely using the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and [iOS Keychain](https://developer.apple.com/documentation/security/keychain-services).
- 🔍 **Detailed Error Messages**: Get actionable error messages with specific failure reasons and error codes on iOS, making debugging keychain issues straightforward.
- 🤝 **Compatibility**: Compatible with the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/), [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/), and [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Secure Preferences plugin is typically used whenever an app needs to keep small pieces of sensitive data on the device, for example:

- **Authentication tokens**: Store OAuth refresh tokens or session tokens that the app reads in the background.
- **API keys**: Keep server-issued API keys encrypted at rest instead of in plain text.
- **Sensitive settings**: Persist preference flags that contain personal information.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.4.x          | >=8.x.x           | Active support |
| 0.3.x          | >=8.x.x           | Deprecated     |
| 0.2.x          | >=8.x.x           | Deprecated     |

## Guides

- [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/)
- [Announcing the Capacitor Secure Preferences Plugin](https://capawesome.io/blog/announcing-the-capacitor-secure-preferences-plugin/)
- [Exploring the Capacitor Secure Preferences API](https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/)
- [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-secure-preferences` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-secure-preferences
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### Web

**Attention**: The web implementation uses `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to store a value, retrieve a value, list all stored keys, remove a value, and clear all stored values.

### Store a value

Store a value securely under a key. On Android and iOS, the value is encrypted at rest. On the web, the value is stored unencrypted in `localStorage` for development purposes only:

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const set = async () => {
  await SecurePreferences.set({
    key: 'refreshToken',
    value: 'eyJhbGciOi...',
  });
};
```

### Retrieve a value

Get the value associated with a key:

```
import { SecurePreferences, ErrorCode } from '@capawesome-team/capacitor-secure-preferences';

const get = async () => {
  try {
    const { value } = await SecurePreferences.get({
      key: 'refreshToken',
    });
    console.log(value);
  } catch (error) {
    if (error.code === ErrorCode.DecryptionFailed) {
      // The value is unreadable; remove it.
      await SecurePreferences.remove({ key: 'refreshToken' });
    } else if (error.code === ErrorCode.KeyInvalidated) {
      // All values are lost; reset the store.
      await SecurePreferences.clear();
    } else {
      throw error;
    }
  }
};
```

### List all stored keys

Get a list of all keys that currently have a stored value:

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const keys = async () => {
  const { keys } = await SecurePreferences.keys();
  console.log(keys);
};
```

### Remove a value

Remove a single value given its key:

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const remove = async () => {
  await SecurePreferences.remove({
    key: 'refreshToken',
  });
};
```

### Clear all stored values

Remove all stored keys and values at once:

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const clear = async () => {
  await SecurePreferences.clear();
};
```

## API

- [`clear()`](#clear)
- [`get(...)`](#get)
- [`keys()`](#keys)
- [`remove(...)`](#remove)
- [`set(...)`](#set)
- [Interfaces](#interfaces)

### clear()

```
clear() => Promise<void>
```

Clear all stored keys and values.

On **Android**, this also resets the encryption key, so the next call to `set(...)` generates a new one.

**Since:** 0.1.0

______________________________________________________________________

### get(...)

```
get(options: GetOptions) => Promise<GetResult>
```

Get the value associated with a key.

On **Android**, this method rejects with the error code `DECRYPTION_FAILED` if the stored value cannot be decrypted and with `KEY_INVALIDATED` if the encryption key can no longer be used.

On **iOS**, this method rejects if the Keychain item cannot be read, for example because the device is locked. The value is only `null` if the key does not exist.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetResult>`

**Since:** 0.1.0

______________________________________________________________________

### keys()

```
keys() => Promise<KeysResult>
```

Get a list of all stored keys.

**Returns:** `Promise<KeysResult>`

**Since:** 0.1.0

______________________________________________________________________

### remove(...)

```
remove(options: RemoveOptions) => Promise<void>
```

Remove a value given its key.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `RemoveOptions` |

**Since:** 0.1.0

______________________________________________________________________

### set(...)

```
set(options: SetOptions) => Promise<void>
```

Set a value given its key.

On **Android**, this method rejects with the error code `KEY_INVALIDATED` if the encryption key can no longer be used.

On **Web**, the value is stored unencrypted in `localStorage`. This is for development purposes only and should NOT be used in production.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `SetOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetResult

| Prop        | Type     | Description | Since                |
| ----------- | -------- | ----------- | -------------------- |
| **`value`** | \`string | null\`      | The retrieved value. |

#### GetOptions

| Prop      | Type     | Description                               | Since |
| --------- | -------- | ----------------------------------------- | ----- |
| **`key`** | `string` | The key associated with the stored value. | 0.1.0 |

#### KeysResult

| Prop       | Type       | Description                | Since |
| ---------- | ---------- | -------------------------- | ----- |
| **`keys`** | `string[]` | The available stored keys. | 0.1.0 |

#### RemoveOptions

| Prop      | Type     | Description        | Since |
| --------- | -------- | ------------------ | ----- |
| **`key`** | `string` | The key to remove. | 0.1.0 |

#### SetOptions

| Prop        | Type     | Description                               | Since |
| ----------- | -------- | ----------------------------------------- | ----- |
| **`key`**   | `string` | The key associated with the stored value. | 0.1.0 |
| **`value`** | `string` | The value to store.                       | 0.1.0 |

## FAQ

### Where is the data stored?

On Android, the encryption key is stored in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and the encrypted values are stored in a `SharedPreferences` file (`CAPAWESOME_SECURE_PREFERENCES.xml`). On iOS, the encrypted values are stored as [Keychain](https://developer.apple.com/documentation/security/keychain-services) items.

On Android, the encryption key in the Keystore is never backed up. The encrypted values in `SharedPreferences` are part of [Android Auto Backup](https://developer.android.com/identity/data/autobackup) by default, but the backed-up ciphertext is unusable on another device without the Keystore key; to exclude the preferences file (`CAPAWESOME_SECURE_PREFERENCES.xml`) from backup, see the [Android documentation](https://developer.android.com/identity/data/autobackup#IncludingFiles). On iOS, the Keychain items are not synced to iCloud, but they may be included in encrypted local device backups and restored on a new device.

### Is the data removed when the app is uninstalled?

On Android, yes: the `SharedPreferences` file and the Keystore key are deleted. On iOS, no: Keychain items survive an uninstall and are available again after a reinstall with the same bundle identifier. Apple does not document or guarantee this behavior.

To start with an empty store after a reinstall, keep a marker in `UserDefaults`, which is removed with the app, and call `clear()` on the first launch when it is missing:

```
import { Preferences } from '@capacitor/preferences';
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const clearAfterReinstall = async () => {
  const { value } = await Preferences.get({ key: 'installed' });
  if (value === null) {
    await SecurePreferences.clear();
    await Preferences.set({ key: 'installed', value: 'true' });
  }
};
```

### How are values encrypted on Android?

Values are encrypted with AES-256-GCM. The 256-bit key is generated on first use and stored in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) under a dedicated alias, so the key material never leaves the Keystore. Installations that already use a 128-bit key from an earlier plugin version keep using it, also for new values; call `clear()` to switch the store to a 256-bit key. Every value is encrypted with a fresh random IV that is stored together with the ciphertext. There is no fallback to a smaller key size: if a 256-bit key cannot be generated, the call fails with an error instead of silently using weaker encryption.

### What happens when the encryption key is invalidated?

On Android, the plugin never replaces an existing Keystore key on its own. If the key exists but can no longer be loaded, `get(...)` and `set(...)` reject with the error code `KEY_INVALIDATED`. If a stored value cannot be decrypted, for example because the ciphertext was modified or was written with a different key, `get(...)` rejects with the error code `DECRYPTION_FAILED`. The stored values cannot be recovered in either case. Call `clear()` to reset the store: it removes all stored values and deletes the Keystore key so that the next `set(...)` starts over with a new key. The plugin cannot distinguish a corrupt key from a rare transient Keystore failure, so an app that wants to rule out the latter can retry the call once before clearing.

### When can the stored values be read on iOS?

The Keychain items are stored with the default accessibility `kSecAttrAccessibleWhenUnlocked`, which means they can only be read while the device is unlocked. A read from a background task on a locked device therefore fails, and `get(...)` rejects with the reported Keychain error instead of resolving `null`. A `null` value means that the key does not exist.

### When should I use Secure Preferences instead of Vault or SQLite?

All three plugins protect data on the device, but they target different problems:

- **Secure Preferences** (this plugin) is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background — typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information.
- **[Vault](https://capawesome.io/docs/sdks/capacitor/vault/)** is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action — a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an "app lock" screen.
- **[SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/)** is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets — for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database.

A quick decision tree:

- Need encrypted key/value storage the app can read freely in the background? → **Secure Preferences**.
- Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? → **Vault**.
- Need queries, relations, or large datasets? → **SQLite**.

The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else.

### Is this plugin an alternative to Ionic Secure Storage?

Yes, for key/value data. This plugin was built as an actively maintained alternative to [Ionic Secure Storage](https://ionic.io/products/secure-storage), which sunsets on December 31, 2027. Like Ionic Secure Storage's key/value API, it stores sensitive data encrypted at rest, backed by the Android Keystore and iOS Keychain. If you use Ionic Secure Storage's encrypted SQLite database, take a look at the [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/) plugin instead, which provides SQLCipher-based encryption.

### How do I migrate from Ionic Secure Storage?

For an AI-assisted migration of your code, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool and instruct it to use the `ionic-enterprise-sdk-migration` skill to migrate your project from Ionic Secure Storage to `@capawesome-team/capacitor-secure-preferences`. Alternatively, if you want to perform the migration manually, you can follow the instructions in this blog post: [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/).

### Can I use the plugin on the web?

Yes, but only for development and testing purposes. The web implementation stores values unencrypted in `localStorage` to make cross-platform development easier and should NOT be used in production. The secure, encrypted storage backed by the Android Keystore and iOS Keychain is only available on Android and iOS.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face or fingerprint recognition.
- [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/): Detect rooted and jailbroken devices before trusting locally stored secrets.
- [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/): Access SQLite databases with support for encryption, transactions, and schema migrations.
- [Vault](https://capawesome.io/docs/sdks/capacitor/vault/): Securely store key/value pairs in lockable, biometric-protected vaults.

## Next steps

Here are a few resources to help you continue:

- Read [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/) if you are migrating from Ionic Secure Storage.
- Need biometric-protected, lockable storage? Check out the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/).
- Need encrypted relational storage? Check out the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/LICENSE).

# Capacitor Settings Launcher Plugin

Capacitor plugin to open native settings screens.

## Features

- ⚙️ **App settings**: Open the settings screen of your app to guide users to grant a denied permission.
- 🔔 **Notification settings**: Open the notification settings screen of your app.
- 🤖 **Android settings**: Open a large catalog of Android system settings screens.
- 🔒 **App Store safe**: Uses only official platform APIs — no private URL schemes.
- 🤝 **Compatibility**: Works alongside the [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/) and [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Settings Launcher plugin is typically used to guide users to the right system settings screen, for example:

- **Permission recovery**: Open your app's settings screen so users can grant a previously denied permission.
- **Notification opt-in**: Guide users to your app's notification settings when notifications are disabled.
- **Connectivity troubleshooting**: Open the Wi-Fi, Bluetooth, or airplane mode settings on Android when your app requires a connection.
- **Onboarding flows**: Send users to Android settings screens such as locale, location, or NFC to enable features your app depends on.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-settings-launcher` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-settings-launcher
npx cap sync
```

### Android

No additional configuration is required for this plugin.

### iOS

The `openNotificationSettings(...)` method requires iOS 16 or later. On older versions, the call rejects as unavailable.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to open your app's settings screen, open your app's notification settings, and open an Android system settings screen.

### Open the settings screen of your app

Open your app's settings screen, for example to guide users to grant a previously denied permission. Only available on Android and iOS:

```
import { SettingsLauncher } from '@capawesome/capacitor-settings-launcher';

const openAppSettings = async () => {
  await SettingsLauncher.openAppSettings();
};
```

### Open the notification settings of your app

Open your app's notification settings screen, for example when the user has disabled notifications. On iOS, this method requires iOS 16 or later and rejects on older versions. Only available on Android and iOS:

```
import { SettingsLauncher } from '@capawesome/capacitor-settings-launcher';

const openNotificationSettings = async () => {
  await SettingsLauncher.openNotificationSettings();
};
```

### Open an Android system settings screen

Use the `AndroidSettingsPage` enum to open one of the many supported Android system settings screens, such as Wi-Fi, Bluetooth, or location. Only available on Android:

```
import { SettingsLauncher, AndroidSettingsPage } from '@capawesome/capacitor-settings-launcher';

const openAndroidSettings = async () => {
  await SettingsLauncher.openAndroidSettings({
    page: AndroidSettingsPage.Wifi,
  });
};
```

## API

- [`openAndroidSettings(...)`](#openandroidsettings)
- [`openAppSettings()`](#openappsettings)
- [`openNotificationSettings()`](#opennotificationsettings)
- [Interfaces](#interfaces)
- [Enums](#enums)

### openAndroidSettings(...)

```
openAndroidSettings(options: OpenAndroidSettingsOptions) => Promise<void>
```

Open a specific Android system settings screen.

Only available on Android.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `OpenAndroidSettingsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### openAppSettings()

```
openAppSettings() => Promise<void>
```

Open the settings screen of your app.

This is the recommended way to guide users to grant a previously denied permission.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### openNotificationSettings()

```
openNotificationSettings() => Promise<void>
```

Open the notification settings screen of your app.

On iOS, this method requires iOS 16 or later and rejects on older versions.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### OpenAndroidSettingsOptions

| Prop       | Type                  | Description                                 | Since |
| ---------- | --------------------- | ------------------------------------------- | ----- |
| **`page`** | `AndroidSettingsPage` | The Android system settings screen to open. | 0.1.0 |

### Enums

#### AndroidSettingsPage

| Members                         | Value                           | Description                                                                                               | Since |
| ------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`Accessibility`**             | `'ACCESSIBILITY'`               | Show settings for accessibility modules.                                                                  | 0.1.0 |
| **`AirplaneMode`**              | `'AIRPLANE_MODE'`               | Show settings to allow entering/exiting airplane mode.                                                    | 0.1.0 |
| **`Apn`**                       | `'APN'`                         | Show settings to allow configuration of APNs.                                                             | 0.1.0 |
| **`BatterySaver`**              | `'BATTERY_SAVER'`               | Show settings to allow configuration of battery saver mode.                                               | 0.1.0 |
| **`Bluetooth`**                 | `'BLUETOOTH'`                   | Show settings to allow configuration of Bluetooth.                                                        | 0.1.0 |
| **`Captioning`**                | `'CAPTIONING'`                  | Show settings for video captioning.                                                                       | 0.1.0 |
| **`CastSettings`**              | `'CAST_SETTINGS'`               | Show settings to allow configuration of cast endpoints.                                                   | 0.1.0 |
| **`DataRoaming`**               | `'DATA_ROAMING'`                | Show settings for selection of 2G/3G.                                                                     | 0.1.0 |
| **`Date`**                      | `'DATE'`                        | Show settings to allow configuration of date and time.                                                    | 0.1.0 |
| **`Development`**               | `'DEVELOPMENT'`                 | Show settings to allow configuration of application development settings.                                 | 0.1.0 |
| **`DeviceInfo`**                | `'DEVICE_INFO'`                 | Show general device information settings (serial number, software version, phone number, etc.).           | 0.1.0 |
| **`Display`**                   | `'DISPLAY'`                     | Show settings to allow configuration of display.                                                          | 0.1.0 |
| **`Dream`**                     | `'DREAM'`                       | Show Daydream settings.                                                                                   | 0.1.0 |
| **`Home`**                      | `'HOME'`                        | Show settings for selecting the default home app.                                                         | 0.1.0 |
| **`IgnoreBatteryOptimization`** | `'IGNORE_BATTERY_OPTIMIZATION'` | Show screen for controlling which apps can ignore battery optimizations.                                  | 0.1.0 |
| **`InputMethod`**               | `'INPUT_METHOD'`                | Show settings to configure input methods, in particular allowing the user to enable input methods.        | 0.1.0 |
| **`InternalStorage`**           | `'INTERNAL_STORAGE'`            | Show settings for internal storage.                                                                       | 0.1.0 |
| **`Locale`**                    | `'LOCALE'`                      | Show settings to allow configuration of locale.                                                           | 0.1.0 |
| **`Location`**                  | `'LOCATION'`                    | Show settings to allow configuration of current location sources.                                         | 0.1.0 |
| **`ManageAllApplications`**     | `'MANAGE_ALL_APPLICATIONS'`     | Show settings to manage all applications.                                                                 | 0.1.0 |
| **`ManageApplications`**        | `'MANAGE_APPLICATIONS'`         | Show settings to manage installed applications.                                                           | 0.1.0 |
| **`MemoryCard`**                | `'MEMORY_CARD'`                 | Show settings for memory card storage.                                                                    | 0.1.0 |
| **`Network`**                   | `'NETWORK'`                     | Show settings for selecting the network operator.                                                         | 0.1.0 |
| **`Nfc`**                       | `'NFC'`                         | Show settings to allow configuration of NFC.                                                              | 0.1.0 |
| **`NfcPayment`**                | `'NFC_PAYMENT'`                 | Show settings to allow configuration of tap and pay.                                                      | 0.1.0 |
| **`NotificationListener`**      | `'NOTIFICATION_LISTENER'`       | Show settings for managing which apps have access to notification listener services.                      | 0.1.0 |
| **`Printing`**                  | `'PRINTING'`                    | Show settings for printing.                                                                               | 0.1.0 |
| **`Privacy`**                   | `'PRIVACY'`                     | Show settings to allow configuration of privacy options.                                                  | 0.1.0 |
| **`Search`**                    | `'SEARCH'`                      | Show settings to allow configuration of search.                                                           | 0.1.0 |
| **`Security`**                  | `'SECURITY'`                    | Show settings to allow configuration of security and location privacy.                                    | 0.1.0 |
| **`Sound`**                     | `'SOUND'`                       | Show settings to allow configuration of sound and volume.                                                 | 0.1.0 |
| **`Sync`**                      | `'SYNC'`                        | Show settings to allow configuration of sync settings.                                                    | 0.1.0 |
| **`Usage`**                     | `'USAGE'`                       | Show screen for controlling which apps can access usage statistics.                                       | 0.1.0 |
| **`UserDictionary`**            | `'USER_DICTIONARY'`             | Show settings to manage the user input dictionary.                                                        | 0.1.0 |
| **`VoiceInput`**                | `'VOICE_INPUT'`                 | Show settings to configure input methods, in particular allowing the user to enable voice input services. | 0.1.0 |
| **`Vpn`**                       | `'VPN'`                         | Show settings to allow configuration of VPN.                                                              | 0.1.0 |
| **`Wifi`**                      | `'WIFI'`                        | Show settings to allow configuration of Wi-Fi.                                                            | 0.1.0 |
| **`Wireless`**                  | `'WIRELESS'`                    | Show settings to allow configuration of wireless controls such as Wi-Fi, Bluetooth and mobile networks.   | 0.1.0 |

## Migrating from `capacitor-native-settings`

This plugin replaces the single `open(...)` method of `capacitor-native-settings` with three explicit methods. Instead of passing an `optionAndroid` and `optionIOS` to a single method, call the method that matches your intent:

| `capacitor-native-settings`                                        | Settings Launcher                         |
| ------------------------------------------------------------------ | ----------------------------------------- |
| `open({ optionAndroid: 'application_details', optionIOS: 'App' })` | `openAppSettings()`                       |
| `open({ optionAndroid: 'app_notification', optionIOS: 'App' })`    | `openNotificationSettings()`              |
| `open({ optionAndroid: '<page>', optionIOS: '...' })`              | `openAndroidSettings({ page: '<page>' })` |

On iOS, `openAppSettings()` and `openNotificationSettings()` cover the officially supported destinations. The various `optionIOS` deep links into specific iOS settings sections are intentionally not supported (see below).

## iOS and the `App-Prefs:` URL scheme

This plugin deliberately does **not** provide deep links into specific iOS system settings sections (e.g. Wi-Fi, Bluetooth, Location). Those links rely on the private `App-Prefs:` URL scheme, which is not part of the public iOS API. Apps that use it risk rejection during App Store review, and Apple may break it without notice between iOS releases.

Instead, this plugin only uses official Apple APIs: `UIApplication.openSettingsURLString` (your app's settings) and `openNotificationSettingsURLString` (your app's notification settings, iOS 16+). This is a deliberate design decision to keep your app App Store safe.

## FAQ

### How is this plugin different from other similar plugins?

It opens native settings screens through three explicit, fully typed methods — your app's settings, your app's notification settings, and a large catalog of Android system screens such as Wi-Fi, Bluetooth, and location — so each call clearly matches your intent. It relies only on official Apple and Android APIs and deliberately avoids the private `App-Prefs:` URL scheme, which keeps your app App Store safe. Actively maintained against the latest Capacitor version, it is built to guide users to exactly the right settings screen on Android and iOS.

### How can I guide users to grant a previously denied permission?

Call the `openAppSettings` method to open the settings screen of your app. This is the recommended way to let users grant a permission that they previously denied, since neither Android nor iOS shows the permission prompt again after a denial. See the [usage example](#open-the-settings-screen-of-your-app) above.

### How does this plugin work with the Permissions plugin?

Use the [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/) plugin's `checkPermissions()` method to detect a `denied` permission state, then call `openAppSettings()` from this plugin to send the user straight to your app's settings screen to grant it manually. The two plugins are commonly used together for this check-then-recover flow.

### Why can't I open specific iOS settings sections like Wi-Fi or Bluetooth?

Deep links into specific iOS system settings sections rely on the private `App-Prefs:` URL scheme, which is not part of the public iOS API. Apps that use it risk rejection during App Store review, and Apple may break it without notice between iOS releases. This plugin deliberately only uses official Apple APIs to keep your app App Store safe (see [iOS and the `App-Prefs:` URL scheme](#ios-and-the-app-prefs-url-scheme)).

### Why does `openNotificationSettings` reject on iOS?

The `openNotificationSettings(...)` method requires iOS 16 or later. On older iOS versions, the call rejects as unavailable. The `openAppSettings()` method works on all supported iOS versions and also gives users access to the notification settings of your app.

### Which Android settings screens can I open?

The `openAndroidSettings(...)` method supports a large catalog of Android system settings screens, including Wi-Fi, Bluetooth, location, locale, NFC, display, sound, and many more. See the `AndroidSettingsPage` enum in the [API reference](#api) for the complete list. This method is only available on Android.

### How do I migrate from `capacitor-native-settings`?

This plugin replaces the single `open(...)` method of `capacitor-native-settings` with three explicit methods: `openAppSettings()`, `openNotificationSettings()` and `openAndroidSettings(...)`. See the [migration guide](#migrating-from-capacitor-native-settings) above for a mapping table.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions on Android.
- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/): Launch arbitrary Android intents.
- [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/): Manage the app's own language override, independent of the device language.
- [App Launcher](https://capawesome.io/docs/sdks/capacitor/app-launcher/): Check if an app can be opened and open it.
- [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/): Check and request device permissions with a unified API.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/settings-launcher/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/settings-launcher/LICENSE).

# Capacitor Shake Plugin

Capacitor plugin to detect shake gestures.

## Features

- 📳 **Shake detection**: Detect physical shake gestures on the device.
- 🎚️ **Sensitivity**: Configure how strong a shake must be to trigger an event.
- 🔋 **Battery-friendly**: The sensor is only active while you are watching for shakes.
- 📱 **Cross-platform**: One consistent API for Android and iOS.
- 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/) and [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Shake plugin is typically used to trigger an action when the user shakes the device, for example:

- **Feedback and bug reporting**: Let users shake the device to open a feedback or bug report dialog.
- **Debug menus**: Open a hidden developer or debug menu in internal builds when the device is shaken.
- **Undo actions**: Offer a shake-to-undo interaction, a gesture many users already know from iOS.
- **Refresh content**: Reload data or shuffle content when a shake gesture is detected.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How shake gestures relate to the Accelerometer and Gyroscope for shake-to-undo and shake-to-reroll interactions.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-shake` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following command:

```
npm install @capawesome/capacitor-shake
npx cap sync
```

This plugin is available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

No additional permissions or privacy descriptions are required.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to detect shake gestures and stop detecting them.

### Detect shake gestures

Attach a `shake` listener and start watching for shake gestures. Use the `sensitivity` option to control how strong a shake must be to trigger an event (see [Sensitivity Levels](#sensitivity-levels)). Only available on Android and iOS:

```
import { Shake } from '@capawesome/capacitor-shake';

const startWatching = async () => {
  await Shake.addListener('shake', () => {
    console.log('Shake detected!');
  });
  await Shake.startWatching({ sensitivity: 'medium' });
};
```

### Stop detecting shake gestures

Stop watching and remove all listeners when you no longer need shake detection, for example when the user leaves the corresponding screen. The sensor is only active while you are watching, so this keeps the plugin battery-friendly:

```
import { Shake } from '@capawesome/capacitor-shake';

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

## API

- [`startWatching(...)`](#startwatching)
- [`stopWatching()`](#stopwatching)
- [`addListener('shake', ...)`](#addlistenershake-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### startWatching(...)

```
startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
```

Start watching for shake gestures.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartWatchingOptions` |

**Since:** 0.1.0

______________________________________________________________________

### stopWatching()

```
stopWatching() => Promise<void>
```

Stop watching for shake gestures.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('shake', ...)

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

Called when a shake gesture is detected.

Only available on Android and iOS.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'shake'`    |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### StartWatchingOptions

| Prop              | Type          | Description                                                                                                                                                 | Default    | Since |
| ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| **`sensitivity`** | `Sensitivity` | The sensitivity of the shake detection. Use `'light'` to detect gentle shakes and `'hard'` to only detect strong shakes. Only available on Android and iOS. | `'medium'` | 0.1.0 |

#### PluginListenerHandle

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

### Type Aliases

#### Sensitivity

`'hard' | 'light' | 'medium'`

## Sensitivity Levels

The `sensitivity` option controls how strong a shake must be to emit a `shake` event:

- `light`: A gentle shake is enough to trigger an event.
- `medium`: A moderate shake is required to trigger an event (default).
- `hard`: Only a strong shake triggers an event.

## FAQ

### How is this plugin different from other similar plugins?

It focuses on doing one thing well: detecting physical shake gestures on Android and iOS through a single, fully typed API. You can tune how strong a shake must be with three sensitivity levels, and the motion sensor only runs between `startWatching(...)` and `stopWatching()`, so it stays battery-friendly. It is actively maintained against the latest Capacitor version, giving you consistent shake behavior on both platforms from one dependency.

### Which platforms are supported by the Shake plugin?

The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented, since browsers do not provide a comparable shake detection API.

### Does shake detection drain the battery?

No, the plugin is designed to be battery-friendly. The motion sensor is only active between `startWatching(...)` and `stopWatching()`, so no sensor data is processed while you are not watching for shakes. Remember to call `stopWatching()` and `removeAllListeners()` when you no longer need shake detection.

### How can I control how strong a shake must be?

Pass the `sensitivity` option to `startWatching(...)`. Use `light` to detect gentle shakes, `medium` (the default) for moderate shakes, or `hard` to only detect strong shakes. See [Sensitivity Levels](#sensitivity-levels) for details.

### Do I need any permissions to detect shake gestures?

No, the plugin does not require any additional permissions or privacy descriptions on Android or iOS. You can install it and start watching for shake gestures right away.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.
- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/): Provide haptic feedback such as impacts, notifications, and vibrations.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/shake/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/shake/LICENSE).

# Capacitor Share Target Plugin

Capacitor plugin to receive content such as text, links, and files from other apps.

## Features

The Capacitor Share Target plugin is one of the most complete solutions for receiving shared content in Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 📝 **Multi-content types**: Handle text, URLs, images, videos, and files.
- 🌐 **Web Share Target API**: Leverage the native sharing capabilities of the web.
- 📦 **Large File Support**: Efficient file caching without memory limitations.
- 🤝 **Compatibility**: Works alongside the [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/), [Clipboard](https://capawesome.io/docs/sdks/capacitor/clipboard/) and [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Share Target plugin is typically used whenever an app wants to appear in the share sheet of the operating system, for example:

- **Media imports**: Receive images and videos shared from the gallery or other apps.
- **Save-for-later apps**: Receive links and text shared from browsers or social media apps, for example in a bookmarking or note-taking app.
- **File handling**: Receive documents such as PDFs shared from other apps for further processing.
- **PWA share target**: Let your Progressive Web App receive shared content via the Web Share Target API.

## Compatibility

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

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-share-target-demo).

| Android | iOS | Web |
| ------- | --- | --- |
|         |     |     |

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-share-target` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-share-target
npx cap sync
```

### Android

#### Intent Filters

To enable your app to receive shared content from other apps, you need to add intent filters to your main activity in `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`).

For example, to handle text, URLs, and other text-based content, add the following intent filter:

```
<intent-filter>
    <action android:name="android.intent.action.SEND" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="text/plain" />
</intent-filter>
```

To handle a single image, add the following intent filter:

```
<intent-filter>
    <action android:name="android.intent.action.SEND" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="image/*" />
</intent-filter>
```

To handle multiple images, add the following intent filter:

```
<intent-filter>
    <action android:name="android.intent.action.SEND_MULTIPLE" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="image/*" />
</intent-filter>
```

You can also add additional intent filters for other MIME types as needed, such as `application/pdf` for PDF files or `video/*` for videos.

**Attention**: Make sure to add these intent filters inside the `<activity>` tag of your main activity, typically `MainActivity`. Also, make sure the activity has the `android:exported="true"` attribute set, which allows other apps to send intents to it. The `android:launchMode="singleTask"` attribute is recommended to prevent multiple instances of your app from being created when receiving shared content.

Here's an example of how your `AndroidManifest.xml` might look like:

```
<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="image/*" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="video/*" />
    </intent-filter>
</activity>
```

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$androidxExifInterfaceVersion` version of `androidx.exifinterface:exifinterface` (default: `1.4.2`)

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

### iOS

On iOS, it's not possible to receive shared content directly in the main app. Instead, you need to create a share extension that can handle the shared content and then communicate it back to your main app. This involves setting up a URL scheme and configuring the share extension to handle the shared content. The communication between the share extension and the main app is done using URL schemes, which allows the share extension to open the main app with the shared content as parameters in the URL.

#### URL Scheme

To enable your app to be opened by the share extension, you need to set up a URL scheme in your iOS app. This is done by adding a URL type in your app's `Info.plist` file. Add the following code to your `Info.plist` file:

```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_URL_SCHEME</string>
        </array>
    </dict>
</array>
```

**Attention**: Replace `YOUR_URL_SCHEME` with your desired URL scheme (e.g. `myapp`). This will allow your app to be opened with URLs like `myapp://?text=Hello%20World`.

#### Share Extension

To enable your app to receive shared content from other apps on iOS, you need to create a share extension. First, you need to add a new target to your Xcode project:

1. Open your Xcode project.
1. Go to `File` > `New` > `Target...`.
1. Select `Share Extension` from the list of templates.
1. Name your extension `AppShare` and click `Finish`.

This will create a new target in your Xcode project with the necessary files for a share extension. If you see a prompt to activate the new scheme, choose "Don't Activate". There is one file called `MainInterface.storyboard` that you should delete **via Xcode**, as we will not need it.

After this, you need to configure the share extension to handle the shared content. Open the `Info.plist` file of your share extension **in a text editor of your choice** and replace its content with the following:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSExtension</key>
    <dict>
        <key>NSExtensionAttributes</key>
        <dict>
            <key>NSExtensionActivationRule</key>
            <dict>
                <key>NSExtensionActivationDictionaryVersion</key>
                <integer>2</integer>
                <key>NSExtensionActivationSupportsWebURLWithMaxCount</key>
                <integer>1</integer>
                <key>NSExtensionActivationSupportsText</key>
                <true/>
                <key>NSExtensionActivationSupportsWebURLWithMaxCount</key>
                <integer>10</integer>
                <key>NSExtensionActivationSupportsFileWithMaxCount</key>
                <integer>10</integer>
                <key>NSExtensionActivationSupportsImageWithMaxCount</key>
                <integer>10</integer>
                <key>NSExtensionActivationSupportsMovieWithMaxCount</key>
                <integer>10</integer>
                <key>NSExtensionActivationSupportsWebPageWithMaxCount</key>
                <integer>1</integer>
            </dict>
        </dict>
        <key>NSExtensionPrincipalClass</key>
        <string>AppShare.ShareViewController</string>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.share-services</string>
    </dict>
</dict>
</plist>
```

Feel free to adjust the `NSExtensionActivationRule` keys to match the types of content you want to support. The example above supports text, web URLs, files, images, and movies.

Next, you need to update the `ShareViewController.swift` file in your share extension target and replace its content with the following code:

```
import MobileCoreServices
import Social
import UIKit
import UniformTypeIdentifiers

struct SharedFileData {
    let uri: String
    let name: String?
    let mimeType: String?
}

class ShareViewController: UIViewController {
    private let appGroupIdentifier = "group.<YOUR_APP_IDENTIFIER>"
    private let urlScheme = "<YOUR_URL_SCHEME>"

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        self.extensionContext!.completeRequest(returningItems: [], completionHandler: nil)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        Task {
            processSharedContent()
        }
    }

    private func openURL(_ url: URL) {
        var responder: UIResponder? = self
        while responder != nil {
            if let application = responder as? UIApplication {
                application.open(url, options: [:], completionHandler: nil)
                return
            }
            responder = responder?.next
        }
    }

    private func sharedContainerURL(for fileName: String) -> URL? {
        guard let containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroupIdentifier) else {
            return nil
        }
        return containerURL.appendingPathComponent(fileName)
    }

    private func removeFileIfExists(at url: URL) throws {
        if FileManager.default.fileExists(atPath: url.path) {
            try FileManager.default.removeItem(at: url)
        }
    }

    private func copyFileToSharedContainer(_ sourceURL: URL) -> String? {
        let fileName = sourceURL.lastPathComponent
        guard let destinationURL = sharedContainerURL(for: fileName) else {
            return nil
        }

        do {
            try removeFileIfExists(at: destinationURL)
            try FileManager.default.copyItem(at: sourceURL, to: destinationURL)
            return destinationURL.absoluteString
        } catch {
            print("Error copying file to shared container: \(error)")
            return nil
        }
    }

    private func copyImageToSharedContainerWithFixedOrientation(_ sourceURL: URL) -> String? {
        let fileName = sourceURL.lastPathComponent
        guard let destinationURL = sharedContainerURL(for: fileName) else {
            return nil
        }

        do {
            try removeFileIfExists(at: destinationURL)

            if let fixedImageData = loadImageDataWithFixedOrientation(from: sourceURL) {
                try fixedImageData.write(to: destinationURL)
            } else {
                try FileManager.default.copyItem(at: sourceURL, to: destinationURL)
            }

            return destinationURL.absoluteString
        } catch {
            print("Error copying image to shared container: \(error)")
            return nil
        }
    }

    private func loadImageDataWithFixedOrientation(from url: URL) -> Data? {
        guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
              let cgImage = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
            return nil
        }

        let uiImage = UIImage(cgImage: cgImage)
        let fixedImage = normalizeImageOrientation(uiImage)

        let fileExtension = url.pathExtension.lowercased()
        if fileExtension == "jpg" || fileExtension == "jpeg" {
            return fixedImage.jpegData(compressionQuality: 0.9)
        } else {
            return fixedImage.pngData()
        }
    }



    private func normalizeImageOrientation(_ image: UIImage) -> UIImage {
        if let fixedImage = image.fixedOrientation() {
            return fixedImage
        }

        return image
    }

    private func extractFileMetadata(from url: URL) -> (name: String, mimeType: String?) {
        let fileName = url.lastPathComponent
        let mimeType = getMimeType(from: url)
        return (fileName, mimeType.isEmpty ? nil : mimeType)
    }

    private func getMimeType(from url: URL) -> String {
        let fileExtension = url.pathExtension as CFString
        guard let extUTI = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, fileExtension, nil)?.takeUnretainedValue() else {
            return ""
        }
        guard let mimeUTI = UTTypeCopyPreferredTagWithClass(extUTI, kUTTagClassMIMEType) else {
            return ""
        }
        return mimeUTI.takeRetainedValue() as String
    }

    private func buildAppURL(textValues: [String], fileValues: [SharedFileData], title: String) -> URL {
        var urlComponents = URLComponents(string: "\(urlScheme)://?")!
        var queryItems: [URLQueryItem] = []

        if !title.isEmpty {
            queryItems.append(URLQueryItem(name: "title", value: title))
        }

        queryItems.append(contentsOf: textValues.filter { !$0.isEmpty }.map {
            URLQueryItem(name: "text", value: $0)
        })

        for (index, file) in fileValues.enumerated() {
            queryItems.append(URLQueryItem(name: "fileUri\(index)", value: file.uri))
            if let name = file.name {
                queryItems.append(URLQueryItem(name: "fileName\(index)", value: name))
            }
            if let mimeType = file.mimeType {
                queryItems.append(URLQueryItem(name: "fileMimeType\(index)", value: mimeType))
            }
        }

        urlComponents.queryItems = queryItems.isEmpty ? nil : queryItems
        return urlComponents.url!
    }

    private func sendData(with textValues: [String], fileValues: [SharedFileData], title: String) {
        let url = buildAppURL(textValues: textValues, fileValues: fileValues, title: title)
        openURL(url)
    }

    private func processImageAttachment(_ attachment: NSItemProvider, dispatchGroup: DispatchGroup, completion: @escaping (SharedFileData?) -> Void) {
        dispatchGroup.enter()
        attachment.loadItem(forTypeIdentifier: UTType.image.identifier, options: nil) { [weak self] (item, _) in
            defer { dispatchGroup.leave() }
            guard let self = self else { 
                completion(nil)
                return 
            }

            if let url = item as? URL {
                if let sharedPath = self.copyImageToSharedContainerWithFixedOrientation(url) {
                    let metadata = self.extractFileMetadata(from: url)
                    completion(SharedFileData(uri: sharedPath, name: metadata.name, mimeType: metadata.mimeType))
                    return
                }
            } else if let image = item as? UIImage {
                let fixedImage = self.normalizeImageOrientation(image)
                if let data = fixedImage.pngData() {
                    let base64String = data.base64EncodedString()
                    completion(SharedFileData(uri: "data:image/png;base64,\(base64String)", name: nil, mimeType: "image/png"))
                    return
                }
            }

            completion(nil)
        }
    }

    private func processMovieAttachment(_ attachment: NSItemProvider, dispatchGroup: DispatchGroup, completion: @escaping (SharedFileData?) -> Void) {
        dispatchGroup.enter()
        attachment.loadItem(forTypeIdentifier: UTType.movie.identifier, options: nil) { [weak self] (item, _) in
            defer { dispatchGroup.leave() }
            guard let self = self else { 
                completion(nil)
                return 
            }

            if let url = item as? URL {
                if let sharedPath = self.copyFileToSharedContainer(url) {
                    let metadata = self.extractFileMetadata(from: url)
                    completion(SharedFileData(uri: sharedPath, name: metadata.name, mimeType: metadata.mimeType))
                    return
                }
            }

            completion(nil)
        }
    }

    private func processPlainTextAttachment(_ attachment: NSItemProvider, dispatchGroup: DispatchGroup, completion: @escaping (String?) -> Void) {
        dispatchGroup.enter()
        attachment.loadItem(forTypeIdentifier: UTType.plainText.identifier, options: nil) { (item, _) in
            defer { dispatchGroup.leave() }

            if let text = item as? String {
                completion(text)
            } else {
                completion(nil)
            }
        }
    }

    private func processURLAttachment(_ attachment: NSItemProvider, dispatchGroup: DispatchGroup, completion: @escaping (String?) -> Void) {
        dispatchGroup.enter()
        attachment.loadItem(forTypeIdentifier: UTType.url.identifier, options: nil) { (item, _) in
            defer { dispatchGroup.leave() }

            if let url = item as? URL {
                completion(url.absoluteString)
            } else {
                completion(nil)
            }
        }
    }

    private func processSharedContent() {
        guard let extensionContext = extensionContext,
              let item = extensionContext.inputItems.first as? NSExtensionItem,
              let attachments = item.attachments else {
            self.extensionContext?.completeRequest(returningItems: [], completionHandler: nil)
            return
        }

        var textValues: [String] = []
        var fileValues: [SharedFileData] = []
        let title = item.attributedTitle?.string ?? item.attributedContentText?.string ?? ""
        let dispatchGroup = DispatchGroup()

        for attachment in attachments {
            if attachment.hasItemConformingToTypeIdentifier(UTType.image.identifier) {
                processImageAttachment(attachment, dispatchGroup: dispatchGroup) { fileData in
                    if let fileData = fileData {
                        fileValues.append(fileData)
                    }
                }
            }

            if attachment.hasItemConformingToTypeIdentifier(UTType.movie.identifier) {
                processMovieAttachment(attachment, dispatchGroup: dispatchGroup) { fileData in
                    if let fileData = fileData {
                        fileValues.append(fileData)
                    }
                }
            }

            if attachment.hasItemConformingToTypeIdentifier(UTType.plainText.identifier) {
                processPlainTextAttachment(attachment, dispatchGroup: dispatchGroup) { text in
                    if let text = text {
                        textValues.append(text)
                    }
                }
            }

            if attachment.hasItemConformingToTypeIdentifier(UTType.url.identifier) {
                processURLAttachment(attachment, dispatchGroup: dispatchGroup) { urlString in
                    if let urlString = urlString {
                        textValues.append(urlString)
                    }
                }
            }
        }

        dispatchGroup.notify(queue: .main) { [weak self] in
            self?.sendData(with: textValues, fileValues: fileValues, title: title)
        }
    }
}

extension UIImage {

    private func applyRotationTransform(for orientation: UIImage.Orientation, to transform: CGAffineTransform, size: CGSize) -> CGAffineTransform {
        var result = transform

        switch orientation {
        case .down, .downMirrored:
            result = result.translatedBy(x: size.width, y: size.height)
            result = result.rotated(by: .pi)
        case .left, .leftMirrored:
            result = result.translatedBy(x: size.width, y: 0)
            result = result.rotated(by: .pi / 2.0)
        case .right, .rightMirrored:
            result = result.translatedBy(x: 0, y: size.height)
            result = result.rotated(by: -.pi / 2.0)
        case .up, .upMirrored:
            break
        @unknown default:
            break
        }

        return result
    }

    private func applyMirrorTransform(for orientation: UIImage.Orientation, to transform: CGAffineTransform, size: CGSize) -> CGAffineTransform {
        var result = transform

        switch orientation {
        case .upMirrored, .downMirrored:
            result = result.translatedBy(x: size.width, y: 0)
            result = result.scaledBy(x: -1, y: 1)
        case .leftMirrored, .rightMirrored:
            result = result.translatedBy(x: size.height, y: 0)
            result = result.scaledBy(x: -1, y: 1)
        case .up, .down, .left, .right:
            break
        @unknown default:
            break
        }

        return result
    }

    private func drawRect(for orientation: UIImage.Orientation, size: CGSize) -> CGRect {
        switch orientation {
        case .left, .leftMirrored, .right, .rightMirrored:
            return CGRect(x: 0, y: 0, width: size.height, height: size.width)
        default:
            return CGRect(x: 0, y: 0, width: size.width, height: size.height)
        }
    }

    func fixedOrientation() -> UIImage? {
        guard imageOrientation != .up else {
            return self.copy() as? UIImage
        }

        guard let cgImage = self.cgImage,
              let colorSpace = cgImage.colorSpace,
              let context = CGContext(data: nil,
                                    width: Int(size.width),
                                    height: Int(size.height),
                                    bitsPerComponent: cgImage.bitsPerComponent,
                                    bytesPerRow: 0,
                                    space: colorSpace,
                                    bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue) else {
            return nil
        }

        var transform = CGAffineTransform.identity
        transform = applyRotationTransform(for: imageOrientation, to: transform, size: size)
        transform = applyMirrorTransform(for: imageOrientation, to: transform, size: size)

        context.concatenate(transform)
        context.draw(cgImage, in: drawRect(for: imageOrientation, size: size))

        guard let newCGImage = context.makeImage() else { return nil }
        return UIImage(cgImage: newCGImage, scale: 1, orientation: .up)
    }
}
```

**Attention**: Replace `<YOUR_URL_SCHEME>` with the URL scheme you defined in your main app's `Info.plist` file (e.g. `myapp`) and `<YOUR_APP_IDENTIFIER>` with your app identifier (e.g. `com.example.app`). Make sure to keep the `group.` prefix for the app group identifier.

Finally, you need to modify the `AppDelegate.swift` file of your main app target to handle the URLs opened by the share extension. Add the missing import and the following code to the `application(_:open:options:)` method:

```
// If you are using Swift Package Manager, add the following import:
+ import ShareTargetPlugin
// Or if you are using CocoaPods, add the following import:
// import CapawesomeTeamCapacitorShareTarget

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
+    // Handle share target URLs
+    let _ = ShareTargetPlugin.handleOpenUrl(url)
+
    // Called when the app was launched with a url. Feel free to add additional processing here,
    // but if you want the App API to support tracking app url opens, make sure to keep this call
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}
```

**Attention**: If you are using **CocoaPods** instead of Swift Package Manager, replace `import ShareTargetPlugin` with `import CapawesomeTeamCapacitorShareTarget`.

#### Capabilities

If you want to receive not only text but also files (e.g., images, videos) from other apps, you need to enable the "App Groups" capability for both your main app and the share extension. This allows both targets to share files in a common container. To do this, follow these steps:

1. Open your Xcode project.
1. Select your app target.
1. Go to the "Signing & Capabilities" tab.
1. Click the "+" button to add a new capability.
1. Select "App Groups" from the list.
1. Create a new app group using the format `group.<YOUR_APP_IDENTIFIER>` (e.g., `group.com.example.app`).
1. Repeat the same steps for your share extension target, ensuring that both targets use the same app group identifier.

If you don't want to receive files, you can skip this step.

## Configuration

No configuration required for this plugin.

## Web

To use this plugin on the web, you need to set up a **Progressive Web App (PWA)** with a web manifest and service worker that handles share targets.

### Manifest

To allow your PWA to act as a share target, you need to add a `share_target` configuration to your web manifest (`manifest.json`):

```
{
  "share_target": {
    "action": "/_share-target",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "title",
      "text": "text", 
      "url": "url",
      "files": [
        {
          "name": "files",
          "accept": ["*/*"]
        }
      ]
    }
  }
}
```

For more information on setting up the share target for your PWA, refer to the [Web Share Target documentation](https://developer.mozilla.org/en-US/docs/Web/Manifest/share_target).

### Service Worker

Since service workers are the only way to intercept network requests in a PWA, you'll need to create one to handle the share target requests. Just create a file named `sw.js` in your project's root directory and add the following code:

```
self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);

  if (event.request.method === 'POST' && url.pathname === '/_share-target') {
    event.respondWith(handleShareTarget(event.request));
  } else if (url.pathname.startsWith('/_share-file/')) {
    event.respondWith(handleFileRequest(event.request));
  }
});

async function handleFileRequest(request) {
  try {
    const url = new URL(request.url);
    const fileId = url.pathname.substring(13); // Remove '/_share-file/' prefix
    const cache = await caches.open('share-target-files');
    const cacheKey = `/${fileId}`;

    const response = await cache.match(cacheKey);
    if (response) {
      return response;
    } else {
      return new Response('File not found', { status: 404 });
    }
  } catch (error) {
    console.error('Error serving file:', error);
    return new Response('Internal error', { status: 500 });
  }
}

async function handleShareTarget(request) {
  try {
    const formData = await request.formData();
    const title = formData.get('title') || '';
    const text = formData.get('text') || '';
    const url = formData.get('url') || '';
    const files = formData.getAll('files');

    const texts = [];
    if (text) texts.push(text);
    if (url) texts.push(url);

    const shareData = {
      title: title,
      texts: texts.length > 0 ? texts : undefined,
      files: undefined,
    };

    if (files.length > 0) {
      const sharedFiles = [];
      const cache = await caches.open('share-target-files');

      for (const file of files) {
        if (file instanceof File && file.size > 0) {
          const fileId = `share-file-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
          const cacheKey = `/${fileId}`;

          const response = new Response(file, {
            headers: {
              'Content-Type': file.type,
              'Content-Length': file.size.toString(),
              'X-File-Name': file.name || 'unknown',
            }
          });
          await cache.put(cacheKey, response);

          sharedFiles.push({
            uri: `/_share-file/${fileId}`,
            name: file.name || undefined,
            mimeType: file.type || undefined,
          });
        }
      }

      if (sharedFiles.length > 0) {
        shareData.files = sharedFiles;
      }
    }

    const redirectUrl = new URL('/', self.location.origin);

    if (shareData.title) {
      redirectUrl.searchParams.set('title', shareData.title);
    }

    if (shareData.texts && shareData.texts.length > 0) {
      shareData.texts.forEach((text, index) => {
        redirectUrl.searchParams.set(`text${index}`, text);
      });
    }

    if (shareData.files && shareData.files.length > 0) {
      shareData.files.forEach((file, index) => {
        redirectUrl.searchParams.set(`fileUri${index}`, file.uri);
        if (file.name) {
          redirectUrl.searchParams.set(`fileName${index}`, file.name);
        }
        if (file.mimeType) {
          redirectUrl.searchParams.set(`fileMimeType${index}`, file.mimeType);
        }
      });
    }

    return Response.redirect(redirectUrl.href, 303);
  } catch (error) {
    console.error('Error handling share target:', error);
    return Response.redirect('/', 303);
  }
}
```

Now, register your service worker in your main JavaScript file:

```
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
```

## Usage

The following example shows how to listen for content shared to your app and load the shared files.

### Listen for shared content

Add a listener for the `shareReceived` event to handle content shared to your app. The event contains the title, text content, and files that were shared. On Android and iOS, load shared files using `Capacitor.convertFileSrc(...)` and the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch); on the web, the file URIs are cached file URLs that can be fetched directly:

```
import { ShareTarget } from '@capawesome-team/capacitor-share-target';
import { Capacitor } from '@capacitor/core';

const addListener = async () => {
    await ShareTarget.addListener('shareReceived', (event) => {
        console.log('Share received:', event);

        // Handle shared files
        if (event.files) {
          event.files.forEach(async (file) => {
            const webPath = Capacitor.convertFileSrc(file.uri);
            const response = await fetch(webPath);
            const blob = await response.blob();
            // Process the file...
          });
        }
    });
};
```

## API

- [`addListener('shareReceived', ...)`](#addlistenersharereceived-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### addListener('shareReceived', ...)

```
addListener(eventName: 'shareReceived', listenerFunc: (event: ShareReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a share is received.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'shareReceived'`                     |
| **`listenerFunc`** | `(event: ShareReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### PluginListenerHandle

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

#### ShareReceivedEvent

| Prop        | Type           | Description                                                                                                                                                          | Since |
| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`title`** | `string`       | The title of the shared content.                                                                                                                                     | 0.1.0 |
| **`texts`** | `string[]`     | The text content that was shared.                                                                                                                                    | 0.1.0 |
| **`files`** | `SharedFile[]` | The files that were shared. On **Android**, only files provided through a `content://` URI of another app are included. Other URIs are ignored for security reasons. | 0.2.0 |

#### SharedFile

| Prop           | Type     | Description                                                                                                                                                                                                            | Since |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`mimeType`** | `string` | The mime type of the shared file.                                                                                                                                                                                      | 0.2.0 |
| **`name`**     | `string` | The name of the shared file with or without extension.                                                                                                                                                                 | 0.2.0 |
| **`uri`**      | `string` | The URI of the shared file. On **Android** and **iOS**, this will contain the file paths or base64 encoded data URLs of the shared files. On **Web**, this will contain cached file URLs that can be fetched directly. | 0.2.0 |

## Troubleshooting

##### `Unable to find compatibility version string for object version XX`

When creating a share extension, you might encounter the following error when building your app:

```
Unable to find compatibility version string for object version 70
```

This error is typically caused by an updated `objectVersion` value in the `project.pbxproj` file of your Xcode project. To resolve this issue, you need to manually revert the `objectVersion` value to a previous version that is compatible with your Xcode version.

## FAQ

### What types of content can my app receive?

The plugin can handle text, URLs, images, videos, and other files. Which content types your app actually receives depends on your configuration: the intent filters in your `AndroidManifest.xml` on Android, the `NSExtensionActivationRule` of your share extension on iOS, and the `share_target` configuration in your web manifest for Progressive Web Apps. See the [Installation](#installation) section for details.

### Why do I need a share extension on iOS?

On iOS, it's not possible to receive shared content directly in the main app. Instead, a share extension handles the shared content and communicates it back to your main app via a URL scheme. The [Installation](#installation) section walks you through creating the share extension, setting up the URL scheme, and handling the URLs in your `AppDelegate.swift`.

### How do I read the files that were shared?

Each shared file contains a `uri` property. On Android and iOS, this contains the file path or a base64 encoded data URL of the shared file, which you can load using `Capacitor.convertFileSrc(...)` and the Fetch API. On the web, the `uri` contains a cached file URL that can be fetched directly. See the [usage example](#listen-for-shared-content) above.

### Why does my app not appear in the share sheet on Android?

Make sure you have added the appropriate intent filters inside the `<activity>` tag of your main activity in `AndroidManifest.xml` for the MIME types you want to receive. Also, the activity must have the `android:exported="true"` attribute set so that other apps can send intents to it, as described in the [Installation](#installation) section.

### Does the plugin work in a Progressive Web App?

Yes, the plugin leverages the Web Share Target API. You need to add a `share_target` configuration to your web manifest and register a service worker that handles the share target requests, as described in the [Web](#web) section.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/): Launch arbitrary Android intents, for example to share content with other apps.
- [Clipboard](https://capawesome.io/docs/sdks/capacitor/clipboard/): Read from and write to the system clipboard.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a received file with the default application.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file, directory, image, or video from the device.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/share-target/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/share-target/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/share-target/LICENSE).

# Capacitor Silent Mode Plugin

Capacitor plugin to detect whether the device is in silent mode.

## Features

- 🔇 **Silent detection**: Check whether the device is currently in silent mode.
- 🔔 **Ringer mode**: Read the exact ringer mode (normal, vibrate or silent) on Android.
- 👂 **Change events**: Listen for changes to the silent mode state.
- 🤝 **Compatibility**: Works alongside the [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/), [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/) and [Volume](https://capawesome.io/docs/sdks/capacitor/volume/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Silent Mode plugin is typically used to adapt an app's audio behavior to the device's ringer state, for example:

- **Respect the mute switch**: Skip sound effects or in-app notification sounds while the device is in silent mode.
- **Muted playback defaults**: Start audio or video content muted when the device is silent.
- **Sound or vibration**: Use the exact ringer mode on Android to decide between playing a sound and vibrating.
- **Live state updates**: React immediately when the user changes the silent mode state using the `silentModeChange` listener.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-silent-mode` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-silent-mode
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On the Web, all methods reject as unimplemented.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the device is in silent mode, read the exact ringer mode, and listen for silent mode changes.

### Check whether the device is in silent mode

Get the current silent mode state of the device. On Android, the device is considered silent if the ringer mode is not set to normal (that is, either vibrate or silent). On iOS, the state is determined using a heuristic (see [Silent Mode Detection](#silent-mode-detection)). Only available on Android and iOS:

```
import { SilentMode } from '@capawesome/capacitor-silent-mode';

const isSilent = async () => {
  const { silent } = await SilentMode.isSilent();
  return silent;
};
```

### Read the exact ringer mode

Read the current ringer mode (`normal`, `vibrate` or `silent`), for example to distinguish between the vibrate and silent modes. Only available on Android:

```
import { SilentMode } from '@capawesome/capacitor-silent-mode';

const getRingerMode = async () => {
  const { mode } = await SilentMode.getRingerMode();
  return mode;
};
```

### Listen for silent mode changes

Attach a listener to be notified when the silent mode state changes. The device is only observed while at least one listener is attached. On iOS, the state is polled on a timer while the app is in the foreground:

```
import { SilentMode } from '@capawesome/capacitor-silent-mode';

const addSilentModeChangeListener = async () => {
  await SilentMode.addListener('silentModeChange', event => {
    console.log('Silent mode changed:', event.silent);
  });
};
```

### Stop listening for changes

Remove all listeners when you no longer need to observe the silent mode state:

```
import { SilentMode } from '@capawesome/capacitor-silent-mode';

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

## API

- [`getRingerMode()`](#getringermode)
- [`isSilent()`](#issilent)
- [`addListener('silentModeChange', ...)`](#addlistenersilentmodechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getRingerMode()

```
getRingerMode() => Promise<GetRingerModeResult>
```

Get the current ringer mode of the device.

Only available on Android.

**Returns:** `Promise<GetRingerModeResult>`

**Since:** 0.1.0

______________________________________________________________________

### isSilent()

```
isSilent() => Promise<IsSilentResult>
```

Get the current silent mode state of the device.

On Android, the device is considered silent if the ringer mode is not set to normal (that is, either vibrate or silent).

On iOS, there is no public API to read the ring/silent switch. The state is therefore determined using a heuristic that plays a short muted system sound and measures how long it takes to complete. The result may be inaccurate while other audio is playing.

Only available on Android and iOS.

**Returns:** `Promise<IsSilentResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('silentModeChange', ...)

```
addListener(eventName: 'silentModeChange', listenerFunc: (event: SilentModeChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the silent mode state of the device.

The device is only observed while at least one listener is attached.

On iOS, the state is polled on a timer while the app is in the foreground and the listener is not called while the app is in the background.

Only available on Android and iOS.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'silentModeChange'`                     |
| **`listenerFunc`** | `(event: SilentModeChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetRingerModeResult

| Prop       | Type         | Description                            | Since |
| ---------- | ------------ | -------------------------------------- | ----- |
| **`mode`** | `RingerMode` | The current ringer mode of the device. | 0.1.0 |

#### IsSilentResult

| Prop         | Type      | Description                                     | Since |
| ------------ | --------- | ----------------------------------------------- | ----- |
| **`silent`** | `boolean` | Whether the device is currently in silent mode. | 0.1.0 |

#### PluginListenerHandle

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

#### SilentModeChangeEvent

| Prop         | Type      | Description                                     | Since |
| ------------ | --------- | ----------------------------------------------- | ----- |
| **`silent`** | `boolean` | Whether the device is currently in silent mode. | 0.1.0 |

### Type Aliases

#### RingerMode

The ringer mode of the device.

- `normal`: The device plays sounds and rings for incoming calls.
- `silent`: The device is silent and does not vibrate.
- `vibrate`: The device is silent but vibrates.

`'normal' | 'silent' | 'vibrate'`

## Silent Mode Detection

Keep the following platform differences in mind when detecting silent mode:

- **Android**: The silent mode state is derived from the [ringer mode](<https://developer.android.com/reference/android/media/AudioManager#getRingerMode()>). A device is considered silent whenever the ringer mode is not `normal`, which means that the vibrate mode also counts as silent. Use `getRingerMode()` if you need to distinguish between the vibrate and silent modes.
- **iOS**: There is no public API to read the state of the ring/silent switch. The plugin therefore relies on a heuristic that plays a short muted system sound and measures how long it takes to complete. As a result, the detection may be inaccurate while other audio is playing or when the audio session category overrides the switch. The `silentModeChange` listener polls this heuristic on a timer while the app is in the foreground and pauses while the app is in the background.

## FAQ

### How is this plugin different from other similar plugins?

It reports whether the device is in silent mode on both Android and iOS, and on Android it also exposes the exact ringer mode so you can distinguish vibrate from fully silent. A `silentModeChange` listener lets you react the moment the state changes, and the device is only observed while a listener is attached. Everything is delivered through a fully typed API that supports CocoaPods and Swift Package Manager on iOS and tracks the latest Capacitor version.

### How does silent mode detection work on iOS?

iOS provides no public API to read the state of the ring/silent switch. The plugin therefore relies on a heuristic that plays a short muted system sound and measures how long it takes to complete. As a result, the detection may be inaccurate while other audio is playing or when the audio session category overrides the switch. See [Silent Mode Detection](#silent-mode-detection) for details.

### Why is vibrate mode reported as silent on Android?

On Android, the device is considered silent whenever the ringer mode is not set to normal, which includes both the vibrate and silent modes. If you need to distinguish between them, use the `getRingerMode` method, which returns the exact ringer mode. This method is only available on Android.

### Can I detect silent mode changes while the app is in the background?

On iOS, no. The `silentModeChange` listener polls the silent mode state on a timer while the app is in the foreground and pauses while the app is in the background. Also note that the device is only observed while at least one listener is attached.

### Is the Silent Mode plugin available on the Web?

No, the plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented, since browsers do not expose the device's ringer state.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session.
- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/): Provide haptic feedback such as impacts, notifications, and vibrations.
- [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/silent-mode/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/silent-mode/LICENSE).

# Capacitor SIM Plugin

Capacitor plugin for reading SIM card and carrier information.

## Features

- 📇 **SIM cards**: Read information about the SIM cards installed on the device.
- 🔀 **Multi-SIM**: Supports devices with multiple SIM slots.
- 🌐 **Carrier details**: Read carrier name, country code, MCC and MNC.
- 🔒 **Permissions**: Built-in handling of the required runtime permission.
- 🤝 **Compatibility**: Works alongside the [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/), [Network](https://capawesome.io/docs/sdks/capacitor/network/) and [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The SIM plugin is typically used when an app needs to know about the device's SIM cards or carrier, for example:

- **Carrier-specific features**: Enable or disable functionality depending on the carrier name or the MCC and MNC of the SIM card.
- **Country detection**: Use the SIM card's ISO country code to preselect a country or region in your app.
- **Multi-SIM handling**: Show which SIM slots are in use on devices with multiple SIM slots.
- **eSIM detection**: Detect whether a SIM card is an embedded SIM (eSIM).

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-sim` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-sim
npx cap sync
```

This plugin is only available on **Android**. On iOS and Web, all methods reject as unimplemented (see [iOS](#ios) below).

### Android

The `READ_PHONE_STATE` permission is declared in the plugin's `AndroidManifest.xml` and is merged into your app automatically. You must request it at runtime via the `requestPermissions(...)` method before calling `getSimCards(...)`.

### iOS

Reading SIM card and carrier information is **not supported** on iOS. Apple deprecated the `CTCarrier` APIs of the Core Telephony framework with iOS 16, and they return placeholder values (e.g. `"--"` and `65535`) on iOS 16.4 and later. Because there is no reliable system API left, all methods reject as unimplemented on iOS.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check and request permissions and read the SIM cards installed on the device.

### Check and request permissions

Reading the SIM cards requires the `READ_PHONE_STATE` runtime permission on Android. Check the current permission state and request the permission before calling `getSimCards(...)`. Only available on Android:

```
import { Sim } from '@capawesome/capacitor-sim';

const checkPermissions = async () => {
  const { readSimCards } = await Sim.checkPermissions();
  return readSimCards;
};

const requestPermissions = async () => {
  const { readSimCards } = await Sim.requestPermissions();
  return readSimCards;
};
```

### Read the SIM cards

Get information about the SIM cards installed on the device, such as the carrier name, country code, MCC and MNC. On devices with multiple SIM slots, all active SIM cards are returned. Only available on Android:

```
import { Sim } from '@capawesome/capacitor-sim';

const getSimCards = async () => {
  const { simCards } = await Sim.getSimCards();
  return simCards;
};
```

## API

- [`checkPermissions()`](#checkpermissions)
- [`getSimCards()`](#getsimcards)
- [`requestPermissions()`](#requestpermissions)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the permission to read the SIM cards.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### getSimCards()

```
getSimCards() => Promise<GetSimCardsResult>
```

Get information about the SIM cards installed on the device.

On devices with multiple SIM slots, all active SIM cards are returned.

Only available on Android.

**Returns:** `Promise<GetSimCardsResult>`

**Since:** 0.1.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the permission to read the SIM cards.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop               | Type              | Description                                    | Since |
| ------------------ | ----------------- | ---------------------------------------------- | ----- |
| **`readSimCards`** | `PermissionState` | The permission state of reading the SIM cards. | 0.1.0 |

#### GetSimCardsResult

| Prop           | Type        | Description                            | Since |
| -------------- | ----------- | -------------------------------------- | ----- |
| **`simCards`** | `SimCard[]` | The SIM cards installed on the device. | 0.1.0 |

#### SimCard

| Prop                    | Type      | Description                              | Since                                                                                                                                                                               |
| ----------------------- | --------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`carrierName`**       | \`string  | null\`                                   | The name of the carrier. Returns `null` if the carrier name is not available.                                                                                                       |
| **`displayName`**       | \`string  | null\`                                   | The user-editable display name of the SIM card. Returns `null` if the display name is not available.                                                                                |
| **`isEmbedded`**        | \`boolean | null\`                                   | Whether the SIM card is an embedded SIM (eSIM). Returns `null` if the information is not available.                                                                                 |
| **`isoCountryCode`**    | \`string  | null\`                                   | The two-letter ISO 3166-1 country code of the carrier. Returns `null` if the country code is not available.                                                                         |
| **`mobileCountryCode`** | \`string  | null\`                                   | The Mobile Country Code (MCC) of the carrier. Returns `null` if the mobile country code is not available.                                                                           |
| **`mobileNetworkCode`** | \`string  | null\`                                   | The Mobile Network Code (MNC) of the carrier. Returns `null` if the mobile network code is not available.                                                                           |
| **`phoneNumber`**       | \`string  | null\`                                   | The phone number associated with the SIM card. This value is often empty because carriers do not reliably store the phone number on the SIM card. In that case, `null` is returned. |
| **`slotIndex`**         | `number`  | The index of the SIM slot on the device. | 0.1.0                                                                                                                                                                               |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

## FAQ

### How is this plugin different from other similar plugins?

It reads the full picture of the device's SIM cards in a single call — carrier name, ISO country code, MCC and MNC, eSIM status, and the slot index for every active card on multi-SIM devices — through a fully typed API that handles the required Android runtime permission for you. It's honest about platform reality, too: SIM data is well supported on Android, while iOS no longer exposes it reliably, so the plugin focuses where the information is actually available. If you only need a rough country hint, a lighter approach may be enough; if you need dependable multi-SIM and carrier details, this plugin is built for exactly that.

### Why is the SIM plugin not available on iOS?

Apple deprecated the `CTCarrier` APIs of the Core Telephony framework with iOS 16, and they return placeholder values (e.g. `"--"` and `65535`) on iOS 16.4 and later. Because there is no reliable system API left for reading SIM card and carrier information, all methods reject as unimplemented on iOS. See the [iOS installation notes](#ios) for details.

### Which permissions are required to read the SIM cards?

The plugin requires the `READ_PHONE_STATE` permission on Android. It is declared in the plugin's `AndroidManifest.xml` and merged into your app automatically, so no manual manifest changes are needed. However, you must request the permission at runtime via the `requestPermissions` method before calling `getSimCards`.

### Why is the phone number `null`?

The `phoneNumber` property is often empty because carriers do not reliably store the phone number on the SIM card. In that case, the plugin returns `null`. Other properties such as `carrierName` or `isoCountryCode` may also be `null` if the information is not available.

### Does the plugin support dual-SIM devices?

Yes, on devices with multiple SIM slots, the `getSimCards` method returns all active SIM cards. Each SIM card includes a `slotIndex` property that indicates the index of the SIM slot on the device.

### Can I detect whether a SIM card is an eSIM?

Yes, each SIM card includes an `isEmbedded` property that indicates whether it is an embedded SIM (eSIM). The property returns `null` if the information is not available.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, and operating system.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sim/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sim/LICENSE).

# Capacitor Singular Plugin

Unofficial Capacitor plugin for the [Singular Mobile SDK](https://support.singular.net/hc/en-us/articles/360037640172-Integrating-a-Singular-SDK-Planning-and-Prerequisites).[1](#fn:1)

## Features

The Capacitor Singular plugin is a modern integration of the Singular Mobile SDK for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📈 **Attribution**: Attribute app installs and re-engagements to your ad campaigns.
- 🎯 **Events & Revenue**: Track standard and custom events as well as in-app revenue.
- 💰 **Ad Revenue**: Report ad revenue from your mediation platform to measure ROAS.
- 🔗 **Singular Links**: Handle deep links and deferred deep links after an install.
- 🍎 **SKAdNetwork**: Let the SDK manage the conversion value or update it yourself.
- 🔒 **Privacy**: Comply with GDPR and CCPA using the built-in consent and opt-out controls.
- 🗑️ **Uninstall Tracking**: Measure uninstalls using push notification device tokens.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

Singular is a Mobile Measurement Partner (MMP). The plugin is typically used to measure and optimize paid user acquisition, for example:

- **Install attribution**: Attribute app installs to the network, campaign and creative that drove them.
- **Campaign optimization**: Report in-app events, purchase revenue and ad revenue to measure ROI and ROAS.
- **Deep linking**: Route users to the right screen with Singular Links, including deferred deep links after an install.
- **Referral programs**: Generate short links that attribute installs to a referring user.
- **Privacy compliance**: Collect consent and honor opt-outs under GDPR and CCPA.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-singular` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-singular
npx cap sync
```

This plugin requires a [Singular](https://www.singular.net/) account. You can find the **SDK Key** and the **SDK Secret** of your app in the Singular dashboard under **Developer Tools → SDK Integration → SDK Keys**. Do not use the Singular Reporting API key, otherwise no SDK data is received.

> [!IMPORTANT] Use of the Singular SDKs is governed by the [Singular Terms & Conditions of Service](https://www.singular.net/terms/), which limit the use of the service to your own advertising and promotions and prohibit sending Protected Health Information (as defined under HIPAA) to Singular (see [Third-Party Notices](#third-party-notices)). This plugin declares the SDKs as dependencies and downloads them from Singular's Maven repository, CocoaPods or Swift Package Manager at build time. It does not bundle or modify them.

### Android

The [Singular SDK for Android](https://support.singular.net/hc/en-us/articles/360037581952-Android-SDK-Basic-Integration) is not published on Maven Central. Add Singular's Maven repository to the `allprojects` section of your `android/build.gradle` file:

```
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.singular.net/' }
    }
}
```

If your project declares its repositories in the `android/settings.gradle` file instead (via `dependencyResolutionManagement`), add the repository there.

#### Permissions

This plugin already declares the `INTERNET`, `ACCESS_NETWORK_STATE` and `com.google.android.gms.permission.AD_ID` permissions in its `AndroidManifest.xml` file, so no manual configuration is required.

Apps that participate in the [Google Play Families program](https://support.google.com/googleplay/android-developer/answer/9893335) must not request the advertising ID. Add the following element to your `AndroidManifest.xml` file before or after the `application` tag to remove the permission:

```
<!-- Required for apps in the Google Play Families program. -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
```

Make sure that the `tools` namespace is declared on the `manifest` element (`xmlns:tools="http://schemas.android.com/tools"`).

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
```

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$singularSdkVersion` version of `com.singular.sdk:singular_sdk` (default: `12.16.0`)

#### Singular Links

To open [Singular Links](https://support.singular.net/hc/en-us/articles/35356520601755-Android-SDK-Supporting-Deep-Links) in your app, add an App Links intent filter to the `MainActivity` in your `AndroidManifest.xml` file:

```
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="YOUR_SUBDOMAIN.sng.link" android:pathPrefix="/A" />
    <data android:scheme="https" android:host="YOUR_SUBDOMAIN.sng.link" android:pathPrefix="/B" />
    <data android:scheme="https" android:host="YOUR_SUBDOMAIN.sng.link" android:pathPrefix="/E" />
    <data android:scheme="https" android:host="YOUR_SUBDOMAIN.sng.link" android:pathPrefix="/F" />
</intent-filter>
```

Replace `YOUR_SUBDOMAIN` with the subdomain of your Singular Links domain. Singular hosts the required `assetlinks.json` file for you, but you must enter the SHA256 fingerprints of your signing keys in the Singular dashboard under **Settings → Apps** so that Android can verify the App Links.

### iOS

The [Singular SDK for iOS](https://github.com/singular-labs/Singular-iOS-SDK) can be integrated via Swift Package Manager (recommended) or CocoaPods. This plugin requires iOS 15 or later.

#### App Tracking Transparency

The SDK only collects the advertising identifier (IDFA) if the user has granted tracking permission. You can request the permission with the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugin. In that case, add the `NSUserTrackingUsageDescription` key to your `ios/App/App/Info.plist` file:

```
<key>NSUserTrackingUsageDescription</key>
<string>The advertising identifier is used to measure the performance of our advertising campaigns.</string>
```

Set `iosWaitForTrackingAuthorizationTimeout` when calling `initialize(...)` so that the SDK waits for the user's decision before it sends the first session.

#### Singular Links

To open Singular Links in your app, add the **Associated Domains** capability to your app in Xcode and add an entry for each Singular Links domain in the format `applinks:YOUR_SUBDOMAIN.sng.link`.

#### SKAdNetwork

[SKAdNetwork](https://support.singular.net/hc/en-us/articles/360047448611-Introduction-to-Singular-s-SKAdNetwork-Solution) support is enabled by default and the SDK manages the conversion value for you. Set `iosManualSkanConversionManagement` to `true` when calling `initialize(...)` if your app manages the conversion value itself. In that case, call `skanRegisterAppForAdNetworkAttribution()` and `skanUpdateConversionValue(...)` yourself.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Initialize the plugin

Add your listeners before calling `initialize(...)` so that no deferred deep link or attribution event is missed:

```
import { Singular } from '@capawesome/capacitor-singular';

const initialize = async () => {
  await Singular.addListener('singularLinkResolved', event => {
    console.log('Singular Link resolved', event.deepLink, event.isDeferred);
  });
  await Singular.addListener('deviceAttributionInfoReceived', event => {
    console.log('Attributed to network', event.network);
  });

  await Singular.initialize({
    apiKey: 'YOUR_SDK_KEY',
    secret: 'YOUR_SDK_SECRET',
  });
};
```

### Track events

Track a standard event or a custom event with attributes:

```
import { Singular } from '@capawesome/capacitor-singular';

const trackLogin = async () => {
  await Singular.trackEvent({
    name: 'sng_login',
  });
};

const trackLevelCompleted = async () => {
  await Singular.trackEvent({
    name: 'level_completed',
    attributes: { level: 3, character: 'warrior' },
  });
};
```

See [Singular Standard Events](https://support.singular.net/hc/en-us/articles/7648172966299-Singular-Standard-Events-Full-List-and-Recommended-Events-by-Vertical) for the list of standard event names and attributes.

### Track revenue

```
import { Singular } from '@capawesome/capacitor-singular';

const trackRevenue = async () => {
  await Singular.trackRevenue({
    amount: 9.99,
    currency: 'USD',
    eventName: 'subscription_purchase',
  });
};
```

### Track ad revenue

```
import { Singular } from '@capawesome/capacitor-singular';

const trackAdRevenue = async () => {
  await Singular.trackAdRevenue({
    adPlatform: 'AdMob',
    adType: 'Rewarded',
    currency: 'USD',
    revenue: 0.05,
  });
};
```

### Set the custom user ID

```
import { Singular } from '@capawesome/capacitor-singular';

const login = async () => {
  await Singular.setCustomUserId({ customUserId: 'user-123' });
};

const logout = async () => {
  await Singular.unsetCustomUserId();
};
```

### Global properties

Global properties are attached to all events. At most 5 global properties can be set:

```
import { Singular } from '@capawesome/capacitor-singular';

const setGlobalProperty = async () => {
  await Singular.setGlobalProperty({ key: 'plan', value: 'premium' });
};

const getGlobalProperties = async () => {
  const { properties } = await Singular.getGlobalProperties();
  return properties;
};

const clearGlobalProperties = async () => {
  await Singular.clearGlobalProperties();
};
```

### Privacy

Notify the SDK about the consent of the user and stop tracking if the user opts out:

```
import { Singular } from '@capawesome/capacitor-singular';

const optIn = async () => {
  await Singular.trackingOptIn();
};

const optOut = async () => {
  await Singular.stopAllTracking();
};

const limitDataSharing = async () => {
  await Singular.setLimitDataSharing({ limit: true });
};
```

Call `resumeAllTracking()` to resume tracking and `trackingUnder13()` if the user is under 13 years old.

### Singular Links

Handle deep links and deferred deep links and create a short link for a referring user:

```
import { Singular } from '@capawesome/capacitor-singular';

const addSingularLinkResolvedListener = async () => {
  await Singular.addListener('singularLinkResolved', event => {
    console.log('Deep link', event.deepLink);
    console.log('Deferred', event.isDeferred);
    console.log('URL parameters', event.urlParameters);
  });
};

const createReferrerShortLink = async () => {
  const { link } = await Singular.createReferrerShortLink({
    baseLink: 'https://myapp.sng.link/A1b2c/d3e4',
    passthroughParameters: { campaign: 'friend-invite' },
    referrerId: 'user-123',
    referrerName: 'Jane Doe',
  });
  return link;
};
```

### SKAdNetwork

Only required if `iosManualSkanConversionManagement` is enabled:

```
import {
  Singular,
  SkanCoarseConversionValue,
} from '@capawesome/capacitor-singular';

const registerAppForAdNetworkAttribution = async () => {
  await Singular.skanRegisterAppForAdNetworkAttribution();
};

const updateConversionValue = async () => {
  await Singular.skanUpdateConversionValue({
    coarseValue: SkanCoarseConversionValue.Medium,
    value: 10,
  });
};

const getConversionValue = async () => {
  const { value } = await Singular.skanGetConversionValue();
  return value;
};
```

### Uninstall tracking

Pass the push notification device token to the SDK. On Android, this is the FCM registration token. On iOS, this is the hex-encoded APNs device token:

```
import { PushNotifications } from '@capacitor/push-notifications';
import { Singular } from '@capawesome/capacitor-singular';

const enableUninstallTracking = async () => {
  await PushNotifications.addListener('registration', async token => {
    await Singular.setDeviceToken({ token: token.value });
  });
  await PushNotifications.register();
};
```

### Singular Device ID

The Singular Device ID (SDID) is resolved by Singular during the first session. Add the listener before calling `initialize(...)`:

```
import { Singular } from '@capawesome/capacitor-singular';

const addSdidReceivedListener = async () => {
  await Singular.addListener('sdidReceived', event => {
    console.log('SDID', event.sdid);
  });
};
```

Set `customSdid` when calling `initialize(...)` to use your own identifier instead. The `sdidSet` event is emitted once it has been stored.

## API

- [`clearGlobalProperties()`](#clearglobalproperties)
- [`createReferrerShortLink(...)`](#createreferrershortlink)
- [`getGlobalProperties()`](#getglobalproperties)
- [`getLimitDataSharing()`](#getlimitdatasharing)
- [`initialize(...)`](#initialize)
- [`isAllTrackingStopped()`](#isalltrackingstopped)
- [`resumeAllTracking()`](#resumealltracking)
- [`setCustomUserId(...)`](#setcustomuserid)
- [`setDeviceToken(...)`](#setdevicetoken)
- [`setGlobalProperty(...)`](#setglobalproperty)
- [`setLimitAdvertisingIdentifiers(...)`](#setlimitadvertisingidentifiers)
- [`setLimitDataSharing(...)`](#setlimitdatasharing)
- [`skanGetConversionValue()`](#skangetconversionvalue)
- [`skanRegisterAppForAdNetworkAttribution()`](#skanregisterappforadnetworkattribution)
- [`skanUpdateConversionValue(...)`](#skanupdateconversionvalue)
- [`stopAllTracking()`](#stopalltracking)
- [`trackAdRevenue(...)`](#trackadrevenue)
- [`trackEvent(...)`](#trackevent)
- [`trackRevenue(...)`](#trackrevenue)
- [`trackingOptIn()`](#trackingoptin)
- [`trackingUnder13()`](#trackingunder13)
- [`unsetCustomUserId()`](#unsetcustomuserid)
- [`unsetGlobalProperty(...)`](#unsetglobalproperty)
- [`addListener('deviceAttributionInfoReceived', ...)`](#addlistenerdeviceattributioninforeceived-)
- [`addListener('sdidReceived', ...)`](#addlistenersdidreceived-)
- [`addListener('sdidSet', ...)`](#addlistenersdidset-)
- [`addListener('singularLinkResolved', ...)`](#addlistenersingularlinkresolved-)
- [`addListener('skanConversionValueUpdated', ...)`](#addlistenerskanconversionvalueupdated-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### clearGlobalProperties()

```
clearGlobalProperties() => Promise<void>
```

Remove all global properties.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### createReferrerShortLink(...)

```
createReferrerShortLink(options: CreateReferrerShortLinkOptions) => Promise<CreateReferrerShortLinkResult>
```

Create a short link that attributes installs to a referring user.

The short link expires after 30 days.

Only available on Android and iOS.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `CreateReferrerShortLinkOptions` |

**Returns:** `Promise<CreateReferrerShortLinkResult>`

**Since:** 0.1.0

______________________________________________________________________

### getGlobalProperties()

```
getGlobalProperties() => Promise<GetGlobalPropertiesResult>
```

Get all global properties.

Only available on Android and iOS.

**Returns:** `Promise<GetGlobalPropertiesResult>`

**Since:** 0.1.0

______________________________________________________________________

### getLimitDataSharing()

```
getLimitDataSharing() => Promise<GetLimitDataSharingResult>
```

Get whether data sharing is limited.

Only available on Android and iOS.

**Returns:** `Promise<GetLimitDataSharingResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the Singular SDK and start the first session.

This method must be called before any other method. Add your listeners before calling this method so that no deferred deep link or attribution event is missed.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isAllTrackingStopped()

```
isAllTrackingStopped() => Promise<IsAllTrackingStoppedResult>
```

Get whether all tracking has been stopped via `stopAllTracking()`.

Only available on Android and iOS.

**Returns:** `Promise<IsAllTrackingStoppedResult>`

**Since:** 0.1.0

______________________________________________________________________

### resumeAllTracking()

```
resumeAllTracking() => Promise<void>
```

Resume all tracking after it was stopped via `stopAllTracking()`.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### setCustomUserId(...)

```
setCustomUserId(options: SetCustomUserIdOptions) => Promise<void>
```

Set the custom user ID that is attached to all sessions and events.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetCustomUserIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setDeviceToken(...)

```
setDeviceToken(options: SetDeviceTokenOptions) => Promise<void>
```

Set the push notification device token used for uninstall tracking.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SetDeviceTokenOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setGlobalProperty(...)

```
setGlobalProperty(options: SetGlobalPropertyOptions) => Promise<void>
```

Set a global property that is attached to all events.

At most 5 global properties can be set. The call is rejected if the property could not be set.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `SetGlobalPropertyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setLimitAdvertisingIdentifiers(...)

```
setLimitAdvertisingIdentifiers(options: SetLimitAdvertisingIdentifiersOptions) => Promise<void>
```

Set whether the SDK is allowed to collect advertising identifiers (e.g. the Google Advertising ID or the IDFA).

Only available on Android and iOS.

| Param         | Type                                    |
| ------------- | --------------------------------------- |
| **`options`** | `SetLimitAdvertisingIdentifiersOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setLimitDataSharing(...)

```
setLimitDataSharing(options: SetLimitDataSharingOptions) => Promise<void>
```

Set whether data sharing with third parties is limited (e.g. after the user opted out under CCPA).

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `SetLimitDataSharingOptions` |

**Since:** 0.1.0

______________________________________________________________________

### skanGetConversionValue()

```
skanGetConversionValue() => Promise<SkanGetConversionValueResult>
```

Get the current SKAdNetwork conversion value.

Only available on iOS.

**Returns:** `Promise<SkanGetConversionValueResult>`

**Since:** 0.1.0

______________________________________________________________________

### skanRegisterAppForAdNetworkAttribution()

```
skanRegisterAppForAdNetworkAttribution() => Promise<void>
```

Register the app for SKAdNetwork attribution.

Only required if `iosManualSkanConversionManagement` is enabled.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### skanUpdateConversionValue(...)

```
skanUpdateConversionValue(options: SkanUpdateConversionValueOptions) => Promise<void>
```

Update the SKAdNetwork conversion value.

Only required if `iosManualSkanConversionManagement` is enabled. The call is rejected if the conversion value could not be updated.

Only available on iOS.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `SkanUpdateConversionValueOptions` |

**Since:** 0.1.0

______________________________________________________________________

### stopAllTracking()

```
stopAllTracking() => Promise<void>
```

Stop all tracking.

This setting persists across app restarts until `resumeAllTracking()` is called.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### trackAdRevenue(...)

```
trackAdRevenue(options: TrackAdRevenueOptions) => Promise<void>
```

Track ad revenue.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `TrackAdRevenueOptions` |

**Since:** 0.1.0

______________________________________________________________________

### trackEvent(...)

```
trackEvent(options: TrackEventOptions) => Promise<void>
```

Track an event.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `TrackEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### trackRevenue(...)

```
trackRevenue(options: TrackRevenueOptions) => Promise<void>
```

Track a revenue event.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `TrackRevenueOptions` |

**Since:** 0.1.0

______________________________________________________________________

### trackingOptIn()

```
trackingOptIn() => Promise<void>
```

Notify the SDK that the user has opted in to tracking (e.g. under GDPR).

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### trackingUnder13()

```
trackingUnder13() => Promise<void>
```

Notify the SDK that the user is under 13 years old so that the SDK does not collect advertising identifiers.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### unsetCustomUserId()

```
unsetCustomUserId() => Promise<void>
```

Remove the custom user ID.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### unsetGlobalProperty(...)

```
unsetGlobalProperty(options: UnsetGlobalPropertyOptions) => Promise<void>
```

Remove a global property.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `UnsetGlobalPropertyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('deviceAttributionInfoReceived', ...)

```
addListener(eventName: 'deviceAttributionInfoReceived', listenerFunc: (event: DeviceAttributionInfoReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when the device attribution information is received.

The event is emitted once after the first session, and only if device attribution is enabled for your Singular account.

Only available on Android and iOS.

| Param              | Type                                                  |
| ------------------ | ----------------------------------------------------- |
| **`eventName`**    | `'deviceAttributionInfoReceived'`                     |
| **`listenerFunc`** | `(event: DeviceAttributionInfoReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('sdidReceived', ...)

```
addListener(eventName: 'sdidReceived', listenerFunc: (event: SdidReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when the Singular Device ID (SDID) is received.

The event is emitted after the first session and on every subsequent launch with the stored SDID.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'sdidReceived'`                     |
| **`listenerFunc`** | `(event: SdidReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('sdidSet', ...)

```
addListener(eventName: 'sdidSet', listenerFunc: (event: SdidSetEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when a custom Singular Device ID (SDID) has been stored.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'sdidSet'`                     |
| **`listenerFunc`** | `(event: SdidSetEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('singularLinkResolved', ...)

```
addListener(eventName: 'singularLinkResolved', listenerFunc: (event: SingularLinkResolvedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when a Singular Link is resolved.

This includes deferred deep links after an install.

Only available on Android and iOS.

| Param              | Type                                         |
| ------------------ | -------------------------------------------- |
| **`eventName`**    | `'singularLinkResolved'`                     |
| **`listenerFunc`** | `(event: SingularLinkResolvedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('skanConversionValueUpdated', ...)

```
addListener(eventName: 'skanConversionValueUpdated', listenerFunc: (event: SkanConversionValueUpdatedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when the SDK updates the SKAdNetwork conversion value.

Only available on iOS.

| Param              | Type                                               |
| ------------------ | -------------------------------------------------- |
| **`eventName`**    | `'skanConversionValueUpdated'`                     |
| **`listenerFunc`** | `(event: SkanConversionValueUpdatedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CreateReferrerShortLinkResult

| Prop       | Type     | Description               | Since |
| ---------- | -------- | ------------------------- | ----- |
| **`link`** | `string` | The generated short link. | 0.1.0 |

#### CreateReferrerShortLinkOptions

| Prop                        | Type                     | Description                                                         | Since |
| --------------------------- | ------------------------ | ------------------------------------------------------------------- | ----- |
| **`baseLink`**              | `string`                 | The Singular Link to shorten.                                       | 0.1.0 |
| **`passthroughParameters`** | `Record<string, string>` | Additional parameters that are passed through to the installed app. | 0.1.0 |
| **`referrerId`**            | `string`                 | The unique identifier of the referring user.                        | 0.1.0 |
| **`referrerName`**          | `string`                 | The name of the referring user.                                     | 0.1.0 |

#### GetGlobalPropertiesResult

| Prop             | Type                     | Description            | Since |
| ---------------- | ------------------------ | ---------------------- | ----- |
| **`properties`** | `Record<string, string>` | The global properties. | 0.1.0 |

#### GetLimitDataSharingResult

| Prop        | Type      | Description                      | Since |
| ----------- | --------- | -------------------------------- | ----- |
| **`limit`** | `boolean` | Whether data sharing is limited. | 0.1.0 |

#### InitializeOptions

| Prop                                         | Type                     | Description                                                                                                                                                                                                                                             | Default | Since |
| -------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`androidFacebookAppId`**                   | `string`                 | The Facebook App ID used for Meta Install Referrer attribution. Only available on Android.                                                                                                                                                              |         | 0.1.0 |
| **`apiKey`**                                 | `string`                 | The SDK key of your Singular account.                                                                                                                                                                                                                   |         | 0.1.0 |
| **`brandedDomains`**                         | `string[]`               | The branded domains that should be resolved as Singular Links.                                                                                                                                                                                          |         | 0.1.0 |
| **`customSdid`**                             | `string`                 | A custom Singular Device ID (SDID) that is used instead of the one generated by Singular.                                                                                                                                                               |         | 0.1.0 |
| **`customUserId`**                           | `string`                 | The custom user ID that is attached to all sessions and events.                                                                                                                                                                                         |         | 0.1.0 |
| **`espDomains`**                             | `string[]`               | The email service provider domains that should be resolved as Singular Links.                                                                                                                                                                           |         | 0.1.0 |
| **`globalProperties`**                       | `Record<string, string>` | Global properties that are attached to all events. Existing global properties with the same key are overridden. At most 5 global properties can be set.                                                                                                 |         | 0.1.0 |
| **`iosManualSkanConversionManagement`**      | `boolean`                | Whether the SKAdNetwork conversion value is managed by your app instead of by the SDK. Only available on iOS.                                                                                                                                           | `false` | 0.1.0 |
| **`iosSkAdNetworkEnabled`**                  | `boolean`                | Whether SKAdNetwork support is enabled. Only available on iOS.                                                                                                                                                                                          | `true`  | 0.1.0 |
| **`iosWaitForTrackingAuthorizationTimeout`** | `number`                 | The number of seconds the SDK waits for the App Tracking Transparency authorization before sending the first session. Set this to a value greater than `0` if you request the tracking authorization right after the app launch. Only available on iOS. | `0`     | 0.1.0 |
| **`limitAdvertisingIdentifiers`**            | `boolean`                | Whether the SDK is not allowed to collect advertising identifiers (e.g. the Google Advertising ID or the IDFA).                                                                                                                                         | `false` | 0.1.0 |
| **`limitDataSharing`**                       | `boolean`                | Whether data sharing with third parties is limited.                                                                                                                                                                                                     | `false` | 0.1.0 |
| **`loggingEnabled`**                         | `boolean`                | Whether debug logging is enabled.                                                                                                                                                                                                                       | `false` | 0.1.0 |
| **`secret`**                                 | `string`                 | The SDK secret of your Singular account.                                                                                                                                                                                                                |         | 0.1.0 |
| **`sessionTimeout`**                         | `number`                 | The number of seconds the app can stay in the background before a new session is started.                                                                                                                                                               | `60`    | 0.1.0 |
| **`shortLinkResolveTimeout`**                | `number`                 | The number of seconds the SDK waits for a short link to be resolved.                                                                                                                                                                                    | `10`    | 0.1.0 |

#### IsAllTrackingStoppedResult

| Prop          | Type      | Description                            | Since |
| ------------- | --------- | -------------------------------------- | ----- |
| **`stopped`** | `boolean` | Whether all tracking has been stopped. | 0.1.0 |

#### SetCustomUserIdOptions

| Prop               | Type     | Description         | Since |
| ------------------ | -------- | ------------------- | ----- |
| **`customUserId`** | `string` | The custom user ID. | 0.1.0 |

#### SetDeviceTokenOptions

| Prop        | Type     | Description                                                                                                                            | Since |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`token`** | `string` | The push notification device token. On Android, this is the FCM registration token. On iOS, this is the hex-encoded APNs device token. | 0.1.0 |

#### SetGlobalPropertyOptions

| Prop                   | Type      | Description                                                          | Default | Since |
| ---------------------- | --------- | -------------------------------------------------------------------- | ------- | ----- |
| **`key`**              | `string`  | The key of the global property.                                      |         | 0.1.0 |
| **`overrideExisting`** | `boolean` | Whether an existing global property with the same key is overridden. | `true`  | 0.1.0 |
| **`value`**            | `string`  | The value of the global property.                                    |         | 0.1.0 |

#### SetLimitAdvertisingIdentifiersOptions

| Prop        | Type      | Description                                                        | Since |
| ----------- | --------- | ------------------------------------------------------------------ | ----- |
| **`limit`** | `boolean` | Whether the SDK is not allowed to collect advertising identifiers. | 0.1.0 |

#### SetLimitDataSharingOptions

| Prop        | Type      | Description                                         | Since |
| ----------- | --------- | --------------------------------------------------- | ----- |
| **`limit`** | `boolean` | Whether data sharing with third parties is limited. | 0.1.0 |

#### SkanGetConversionValueResult

| Prop        | Type     | Description | Since                                                                                  |
| ----------- | -------- | ----------- | -------------------------------------------------------------------------------------- |
| **`value`** | \`number | null\`      | The fine-grained conversion value (`0` - `63`) or `null` if no value has been set yet. |

#### SkanUpdateConversionValueOptions

| Prop              | Type                        | Description                                                                  | Default | Since |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------- | ------- | ----- |
| **`coarseValue`** | `SkanCoarseConversionValue` | The coarse conversion value. Only available on iOS 16.1+.                    |         | 0.1.0 |
| **`lockWindow`**  | `boolean`                   | Whether the conversion window should be locked. Only available on iOS 16.1+. | `false` | 0.1.0 |
| **`value`**       | `number`                    | The fine-grained conversion value (`0` - `63`).                              |         | 0.1.0 |

#### TrackAdRevenueOptions

| Prop                  | Type     | Description                                          | Since |
| --------------------- | -------- | ---------------------------------------------------- | ----- |
| **`adGroupId`**       | `string` | The identifier of the ad group.                      | 0.1.0 |
| **`adGroupName`**     | `string` | The name of the ad group.                            | 0.1.0 |
| **`adGroupPriority`** | `string` | The priority of the ad group.                        | 0.1.0 |
| **`adGroupType`**     | `string` | The type of the ad group.                            | 0.1.0 |
| **`adPlacementName`** | `string` | The name of the ad placement.                        | 0.1.0 |
| **`adPlatform`**      | `string` | The ad mediation platform that reported the revenue. | 0.1.0 |
| **`adType`**          | `string` | The type of the ad.                                  | 0.1.0 |
| **`adUnitId`**        | `string` | The identifier of the ad unit.                       | 0.1.0 |
| **`adUnitName`**      | `string` | The name of the ad unit.                             | 0.1.0 |
| **`currency`**        | `string` | The currency of the revenue as ISO 4217 code.        | 0.1.0 |
| **`impressionId`**    | `string` | The identifier of the ad impression.                 | 0.1.0 |
| **`networkName`**     | `string` | The name of the ad network that served the ad.       | 0.1.0 |
| **`placementId`**     | `string` | The identifier of the placement.                     | 0.1.0 |
| **`precision`**       | `string` | The precision of the reported revenue.               | 0.1.0 |
| **`revenue`**         | `number` | The revenue amount.                                  | 0.1.0 |

#### TrackEventOptions

| Prop             | Type                     | Description                                                                                                                                       | Since      |
| ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| **`attributes`** | \`Record\<string, string | number                                                                                                                                            | boolean>\` |
| **`name`**       | `string`                 | The name of the event. Can be a standard event name (e.g. `sng_login`, `sng_tutorial_complete`) or a custom event name. Limited to 32 characters. | 0.1.0      |

#### TrackRevenueOptions

| Prop             | Type                     | Description                                                                                                                | Since      |
| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| **`amount`**     | `number`                 | The revenue amount.                                                                                                        | 0.1.0      |
| **`attributes`** | \`Record\<string, string | number                                                                                                                     | boolean>\` |
| **`currency`**   | `string`                 | The currency of the revenue as ISO 4217 code.                                                                              | 0.1.0      |
| **`eventName`**  | `string`                 | The name of the event. If provided, a custom revenue event with this name is tracked instead of the default revenue event. | 0.1.0      |

#### UnsetGlobalPropertyOptions

| Prop      | Type     | Description                     | Since |
| --------- | -------- | ------------------------------- | ----- |
| **`key`** | `string` | The key of the global property. | 0.1.0 |

#### PluginListenerHandle

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

#### DeviceAttributionInfoReceivedEvent

| Prop                  | Type     | Description                                                                 | Since |
| --------------------- | -------- | --------------------------------------------------------------------------- | ----- |
| **`campaignId`**      | `string` | The identifier of the campaign.                                             | 0.1.0 |
| **`campaignName`**    | `string` | The name of the campaign.                                                   | 0.1.0 |
| **`clickTimestamp`**  | `number` | The timestamp of the attributed click in milliseconds since the Unix epoch. | 0.1.0 |
| **`creativeId`**      | `string` | The identifier of the creative.                                             | 0.1.0 |
| **`creativeName`**    | `string` | The name of the creative.                                                   | 0.1.0 |
| **`matchType`**       | `string` | The type of the attribution match.                                          | 0.1.0 |
| **`network`**         | `string` | The name of the attributed network.                                         | 0.1.0 |
| **`passthrough`**     | `string` | The passthrough parameters of the attributed link.                          | 0.1.0 |
| **`subcampaignId`**   | `string` | The identifier of the sub campaign.                                         | 0.1.0 |
| **`subcampaignName`** | `string` | The name of the sub campaign.                                               | 0.1.0 |

#### SdidReceivedEvent

| Prop       | Type     | Description             | Since |
| ---------- | -------- | ----------------------- | ----- |
| **`sdid`** | `string` | The Singular Device ID. | 0.1.0 |

#### SdidSetEvent

| Prop       | Type     | Description             | Since |
| ---------- | -------- | ----------------------- | ----- |
| **`sdid`** | `string` | The Singular Device ID. | 0.1.0 |

#### SingularLinkResolvedEvent

| Prop                | Type                     | Description                                                                | Since                                       |
| ------------------- | ------------------------ | -------------------------------------------------------------------------- | ------------------------------------------- |
| **`deepLink`**      | \`string                 | null\`                                                                     | The deep link value of the Singular Link.   |
| **`isDeferred`**    | `boolean`                | Whether the link is a deferred deep link (i.e. resolved after an install). | 0.1.0                                       |
| **`passthrough`**   | \`string                 | null\`                                                                     | The passthrough value of the Singular Link. |
| **`urlParameters`** | `Record<string, string>` | The query parameters of the Singular Link.                                 | 0.1.0                                       |

#### SkanConversionValueUpdatedEvent

| Prop              | Type                        | Description                                                           | Since                                                     |
| ----------------- | --------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| **`coarseValue`** | \`SkanCoarseConversionValue | null\`                                                                | The coarse conversion value. Only available on iOS 16.1+. |
| **`lockWindow`**  | `boolean`                   | Whether the conversion window is locked. Only available on iOS 16.1+. | 0.1.0                                                     |
| **`value`**       | \`number                    | null\`                                                                | The fine-grained conversion value (`0` - `63`).           |

### Enums

#### SkanCoarseConversionValue

| Members      | Value      | Since |
| ------------ | ---------- | ----- |
| **`High`**   | `'HIGH'`   | 0.1.0 |
| **`Low`**    | `'LOW'`    | 0.1.0 |
| **`Medium`** | `'MEDIUM'` | 0.1.0 |

## FAQ

### Do I need a Singular account to use this plugin?

Yes. This plugin wraps the official Singular SDKs, which require a [Singular](https://www.singular.net/) account, an SDK key and an SDK secret.

### Where do I find the SDK key and the SDK secret?

Both are available in the Singular dashboard under **Developer Tools → SDK Integration → SDK Keys**. Do not use the Singular Reporting API key, otherwise no SDK data is received.

### Do I have to call `initialize(...)` before all other methods?

Yes. All other methods reject with the error code `NOT_INITIALIZED` until `initialize(...)` has been called.

### Why should I add my listeners before calling `initialize(...)`?

The SDK resolves deferred deep links and reports the device attribution information during the first session. If you add the listeners after calling `initialize(...)`, these events may be emitted before your listeners are attached and are therefore missed.

### Does `stopAllTracking()` persist across app restarts?

Yes. Tracking stays stopped until you call `resumeAllTracking()`, even if the app is restarted in between. You can check the current state with `isAllTrackingStopped()`.

### Are there any limits for event names, attributes and global properties?

Yes. Event names are limited to 32 characters, attribute keys and values to 500 characters, and at most 5 global properties can be set. Currencies must be passed as upper case ISO 4217 codes (e.g. `USD`).

### Do I have to handle deep links that open the app while it is already running?

No. The plugin handles warm starts for you by re-initializing the SDK with the new link so that the `singularLinkResolved` event is emitted. On Android, this requires the default `singleTask` launch mode of Capacitor's `MainActivity`.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the tracking permission required to collect the IDFA on iOS.
- [Install Referrer](https://capawesome.io/docs/sdks/capacitor/install-referrer/): Read install attribution data from the Play Install Referrer and Apple Ad Services.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for the PostHog product analytics platform.
- [TikTok App Events](https://capawesome.io/docs/sdks/capacitor/tiktok-app-events/): Unofficial Capacitor plugin for the TikTok App Events SDK.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/singular/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/singular/LICENSE).

## Third-Party Notices

The Singular SDK for iOS is licensed under the [MIT license](https://github.com/singular-labs/Singular-iOS-SDK/blob/master/LICENSE) and is distributed via CocoaPods and Swift Package Manager. The Singular SDK for Android is distributed as a binary artifact from Singular's Maven repository and does not declare a license. Use of both SDKs is additionally governed by the [Singular Terms & Conditions of Service](https://www.singular.net/terms/), which limit the use of the service to your own advertising and promotions and prohibit sending Protected Health Information (as defined under HIPAA) to Singular. This plugin only declares these SDKs as dependencies and does not bundle or modify them. The MIT license of this plugin covers the wrapper code only, not the Singular SDKs.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Singular Labs, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor SMS Composer Plugin

Capacitor plugin to open the native SMS composer prefilled with recipients and a message body.

## Features

- ✉️ **Compose**: Open the native SMS composer prefilled with recipients and a message body.
- ✅ **Capability check**: Check whether the device is able to compose and send SMS messages.
- 🔒 **Privacy-friendly**: The user always reviews and sends the message. The plugin never sends SMS on its own.
- 🤝 **Compatibility**: Works alongside the [Android SMS Retriever](https://capawesome.io/docs/sdks/capacitor/android-sms-retriever/), [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/) and [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The SMS Composer plugin is typically used whenever an app wants to hand off a prefilled text message to the user, for example:

- **Invite friends**: Prefill an invitation message with a download link that users can send to their contacts.
- **Share content**: Let users share an article, a product, or a coupon code via text message.
- **Contact support**: Open the composer prefilled with your support phone number and a message template.
- **Feature detection**: Hide SMS-related features on devices without SMS capability, such as Wi-Fi-only tablets, using `canComposeSms`.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-sms-composer` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-sms-composer
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

### Android

No additional configuration is required. The plugin declares the necessary `<queries>` element for the `smsto` scheme in its `AndroidManifest.xml`, so the SMS capability can be detected on Android 11 (API level 30) and higher.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether the device can send SMS messages and open the native SMS composer.

### Check whether the device can send SMS messages

Check whether the device is able to compose and send SMS messages, for example to hide SMS-related features on devices without SMS capability such as Wi-Fi-only tablets or iPads. Only available on Android and iOS:

```
import { SmsComposer } from '@capawesome/capacitor-sms-composer';

const canComposeSms = async () => {
  const { canCompose } = await SmsComposer.canComposeSms();
  return canCompose;
};
```

### Open the SMS composer

Open the native SMS composer prefilled with recipients and a message body. The user reviews the message and decides whether to send it; the plugin never sends the message itself. The call resolves with a `status` once the composer is dismissed (see [Result Status](#result-status)). Only available on Android and iOS:

```
import { SmsComposer } from '@capawesome/capacitor-sms-composer';

const composeSms = async () => {
  const { status } = await SmsComposer.composeSms({
    recipients: ['+41791234567'],
    body: 'Hello from Capacitor!',
  });
  return status;
};
```

## API

- [`canComposeSms()`](#cancomposesms)
- [`composeSms(...)`](#composesms)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### canComposeSms()

```
canComposeSms() => Promise<CanComposeSmsResult>
```

Check whether the device is able to compose and send SMS messages.

On devices without SMS capability (e.g. Wi-Fi-only tablets or iPads), this resolves with `canCompose` set to `false`.

Only available on Android and iOS.

**Returns:** `Promise<CanComposeSmsResult>`

**Since:** 0.1.0

______________________________________________________________________

### composeSms(...)

```
composeSms(options: ComposeSmsOptions) => Promise<ComposeSmsResult>
```

Open the native SMS composer prefilled with the given recipients and body.

The user reviews the message and decides whether to send it. The plugin never sends the message itself.

The call resolves once the composer is dismissed. If the device is not able to compose SMS messages, the call rejects as unavailable.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `ComposeSmsOptions` |

**Returns:** `Promise<ComposeSmsResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CanComposeSmsResult

| Prop             | Type      | Description                                                  | Since |
| ---------------- | --------- | ------------------------------------------------------------ | ----- |
| **`canCompose`** | `boolean` | Whether the device is able to compose and send SMS messages. | 0.1.0 |

#### ComposeSmsResult

| Prop         | Type               | Description                                                                                                                                                        | Since |
| ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`status`** | `SmsComposeStatus` | The status of the SMS composer after it was dismissed. On Android, the status is always `unknown` because the system does not report whether the message was sent. | 0.1.0 |

#### ComposeSmsOptions

| Prop             | Type       | Description                                                | Since |
| ---------------- | ---------- | ---------------------------------------------------------- | ----- |
| **`body`**       | `string`   | The message body to prefill in the composer.               | 0.1.0 |
| **`recipients`** | `string[]` | The recipients (phone numbers) to prefill in the composer. | 0.1.0 |

### Type Aliases

#### SmsComposeStatus

The status of the SMS composer after it was dismissed.

- `sent`: The user sent the message.
- `canceled`: The user canceled the composer without sending the message.
- `unknown`: The result is unknown. This is always the case on Android.

`'canceled' | 'sent' | 'unknown'`

## Result Status

The `composeSms(...)` method resolves with a `status` once the composer is dismissed:

- On **iOS**, the status reflects the actual outcome (`sent`, `canceled`).
- On **Android**, the status is always `unknown` because the system does not report whether the message was sent.

## Multiple Recipients

Multiple recipients are joined with a semicolon (`;`) in the underlying `smsto:` URI on Android. Some messaging apps expect a comma (`,`) instead, so multi-recipient prefilling may not work reliably across all Android messaging apps.

## FAQ

### How is this plugin different from other similar plugins?

It opens the native SMS composer prefilled with recipients and a message body through a fully typed API, with a `canComposeSms()` check so you can hide the feature on devices without SMS capability such as Wi-Fi-only tablets. The user always reviews and sends the message, so no SMS permissions are needed, and on iOS you get the real send status back. If you only need a basic `smsto:` link, that's simple enough; if you want capability detection and a consistent composer across Android and iOS, this plugin is designed for exactly that.

### Does the plugin send SMS messages automatically?

No, the plugin never sends SMS messages on its own. It opens the native SMS composer prefilled with the recipients and message body you provide, and the user always reviews the message and decides whether to send it. This makes the plugin privacy-friendly and avoids the need for any SMS permissions.

### Why is the status always `unknown` on Android?

On Android, the system does not report whether the message was sent after the composer is dismissed, so the `status` is always `unknown`. On iOS, the status reflects the actual outcome (`sent` or `canceled`). See [Result Status](#result-status) for details.

### How can I detect devices that cannot send SMS messages?

Call the `canComposeSms` method, which resolves with `canCompose` set to `false` on devices without SMS capability, such as Wi-Fi-only tablets or iPads. If you call `composeSms` on such a device anyway, the call rejects as unavailable.

### Why does prefilling multiple recipients not work in some Android messaging apps?

On Android, multiple recipients are joined with a semicolon (`;`) in the underlying `smsto:` URI, but some messaging apps expect a comma (`,`) instead. Multi-recipient prefilling may therefore not work reliably across all Android messaging apps. See [Multiple Recipients](#multiple-recipients) for details.

### Is any additional configuration required on Android?

No, the plugin works out of the box. It declares the necessary `<queries>` element for the `smsto` scheme in its own `AndroidManifest.xml`, so the SMS capability can be detected on Android 11 (API level 30) and higher without manual manifest changes.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Android SMS Retriever](https://capawesome.io/docs/sdks/capacitor/android-sms-retriever/): OTP autofill on Android via the SMS User Consent and Phone Number Hint APIs.
- [Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/): Read, write, or select device contacts.
- [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/): Open the native email composer.
- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sms-composer/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sms-composer/LICENSE).

# Capacitor Speech Recognition Plugin

Capacitor plugin to transcribe speech into text (also known as speech-to-text) with advanced features like silence detection, contextual strings, and more.

## Features

The Capacitor Speech Recognition plugin is one of the most complete speech-to-text solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🌐 **Multiple Languages**: Supports many different languages.
- 🔑 **Permissions**: Check and request permissions for recording audio.
- 🔊 **Events**: Listen for events like `start`, `end`, `speechStart`, `speechEnd`, `error`, `partialResults`, and `results`.
- 🔇 **Silence Detection**: Automatically detects silence to stop the recording.
- 📊 **Silence Threshold**: Define what's considered "silence" for your recordings.
- 💬 **Contextual Strings**: Provide an array of phrases that should be recognized, even if they are not in the system vocabulary.
- 📱 **On-Device Recognition**: Force on-device-only speech recognition, query available on-device languages, and download language models.
- 🧠 **SpeechTranscriber**: Opt-in support for Apple's modern `SpeechTranscriber` API (iOS 26+) with fully on-device processing and no "Speech data will be sent to Apple" permission dialog.
- ⚔️ **Battle-Tested**: Used in more than 250 projects.
- 🤝 **Compatibility**: Compatible with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/), [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Speech Recognition plugin is typically used whenever an app needs to turn spoken words into text, for example:

- **Voice dictation**: Let users dictate messages, notes, or form inputs instead of typing, with live feedback via the `partialResult` event.
- **Voice commands**: Trigger actions in your app by recognizing spoken phrases, using contextual strings to reliably detect custom terms that are not in the system vocabulary.
- **Voice search**: Let users search your app hands-free by speaking their query instead of typing it.
- **Privacy-sensitive transcription**: Force on-device speech recognition so that no audio is sent to external servers.
- **Accessibility**: Offer users with limited mobility an alternative way to enter text.

## 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     |

## Guides

- [Exploring the Capacitor Speech Recognition API](https://capawesome.io/blog/exploring-the-capacitor-speech-recognition-api/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-speech-recognition` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-speech-recognition
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSSpeechRecognitionUsageDescription` and `NSMicrophoneUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why the app needs access to speech recognition and the microphone:

```
<key>NSSpeechRecognitionUsageDescription</key>
<string>Speech recognition is used to transcribe speech into text.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone is used to record audio for speech recognition.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check availability and permissions, start and stop listening, query the recognizer state and available languages, and handle recognition events.

### Check if speech recognition is available

Check whether the speech recognizer is available on the device before offering the feature to the user:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const isAvailable = async () => {
  const { isAvailable } = await SpeechRecognition.isAvailable();
  return isAvailable;
};
```

### Check and request permissions

Speech recognition requires permission to record audio and, on iOS, to use speech recognition. Check and request the permissions before you start listening:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const checkPermissions = async () => {
  const { audioRecording, speechRecognition } = await SpeechRecognition.checkPermissions();
};

const requestPermissions = async () => {
  const { audioRecording, speechRecognition } = await SpeechRecognition.requestPermissions({
    permissions: ['audioRecording', 'speechRecognition'],
  });
};
```

### Start and stop listening

Start listening for speech in a specific language. The `silenceThreshold` option automatically stops the recognition after the given number of milliseconds of silence. You can also stop listening manually:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const startListening = async () => {
  await SpeechRecognition.startListening({
    language: 'en-US',
    silenceThreshold: 2000,
  });
};

const stopListening = async () => {
  await SpeechRecognition.stopListening();
};
```

### Check if the recognizer is listening

Query whether the speech recognizer is currently listening:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const isListening = async () => {
  const { isListening } = await SpeechRecognition.isListening();
  return isListening;
};
```

### Get the available languages

Retrieve the supported languages for speech recognition as BCP-47 language tags. Only available on Android and iOS:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const getLanguages = async () => {
  const { languages } = await SpeechRecognition.getLanguages();
  return languages;
};
```

### Listen for recognition events

React to the different stages of the recognition, for example to display partial results while the user is still speaking:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const addListeners = () => {
  SpeechRecognition.addListener('start', () => {
    console.log('Speech recognition started');
  });
  SpeechRecognition.addListener('end', () => {
    console.log('Speech recognition ended');
  });
  SpeechRecognition.addListener('error', (event) => {
    console.error('Speech recognition error:', event.message);
  });
  SpeechRecognition.addListener('partialResult', (event) => {
    console.log('Partial result:', event.result);
  });
  SpeechRecognition.addListener('result', (event) => {
    console.log('Final result:', event.result);
  });
  SpeechRecognition.addListener('soundLevel', (event) => {
    console.log('Sound level:', event.level);
  });
  SpeechRecognition.addListener('speechStart', () => {
    console.log('User started speaking');
  });
  SpeechRecognition.addListener('speechEnd', () => {
    console.log('User stopped speaking');
  });
};
```

### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

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

## API

- [`getLanguages()`](#getlanguages)
- [`getOnDeviceLanguages()`](#getondevicelanguages)
- [`downloadOnDeviceLanguage(...)`](#downloadondevicelanguage)
- [`isAvailable()`](#isavailable)
- [`isListening()`](#islistening)
- [`startListening(...)`](#startlistening)
- [`stopListening(...)`](#stoplistening)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions(...)`](#requestpermissions)
- [`addListener('end', ...)`](#addlistenerend-)
- [`addListener('error', ...)`](#addlistenererror-)
- [`addListener('partialResult', ...)`](#addlistenerpartialresult-)
- [`addListener('result', ...)`](#addlistenerresult-)
- [`addListener('speechEnd', ...)`](#addlistenerspeechend-)
- [`addListener('speechStart', ...)`](#addlistenerspeechstart-)
- [`addListener('start', ...)`](#addlistenerstart-)
- [`addListener('soundLevel', ...)`](#addlistenersoundlevel-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### getLanguages()

```
getLanguages() => Promise<GetLanguagesResult>
```

Get the available languages for speech recognition.

**Attention**: On Android, this method is unfortunately not supported by all devices. If the method is not supported, the promise will never resolve. It's recommended to set a timeout for the promise.

Only available on Android and iOS.

**Returns:** `Promise<GetLanguagesResult>`

**Since:** 6.0.0

______________________________________________________________________

### getOnDeviceLanguages()

```
getOnDeviceLanguages() => Promise<GetOnDeviceLanguagesResult>
```

Get the available on-device languages for speech recognition.

Only available on Android (SDK 33+) and iOS (26+).

**Returns:** `Promise<GetOnDeviceLanguagesResult>`

**Since:** 8.1.0

______________________________________________________________________

### downloadOnDeviceLanguage(...)

```
downloadOnDeviceLanguage(options: DownloadOnDeviceLanguageOptions, callback: DownloadOnDeviceLanguageCallback) => Promise<CallbackId>
```

Download an on-device language model for speech recognition.

**Note**: On Android, this might trigger user interaction to approve the download.

**Note**: On Android (SDK 33), the `callback` is never invoked because progress tracking is only available on SDK 34+. Use {@link getOnDeviceLanguages} to verify when the download completes.

Only available on Android (SDK 33+) and iOS (26+).

| Param          | Type                               |
| -------------- | ---------------------------------- |
| **`options`**  | `DownloadOnDeviceLanguageOptions`  |
| **`callback`** | `DownloadOnDeviceLanguageCallback` |

**Returns:** `Promise<string>`

**Since:** 8.1.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the speech recognizer is available on the device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 6.0.0

______________________________________________________________________

### isListening()

```
isListening() => Promise<IsListeningResult>
```

Check if the speech recognizer is currently listening.

**Returns:** `Promise<IsListeningResult>`

**Since:** 6.0.0

______________________________________________________________________

### startListening(...)

```
startListening(options?: StartListeningOptions | undefined) => Promise<void>
```

Start listening for speech.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `StartListeningOptions` |

**Since:** 6.0.0

______________________________________________________________________

### stopListening(...)

```
stopListening(options?: StopListeningOptions | undefined) => Promise<void>
```

Stop listening for speech.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StopListeningOptions` |

**Since:** 6.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for the plugin.

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(permissions?: SpeechRecognitionPluginPermission | undefined) => Promise<PermissionStatus>
```

Request permissions for the plugin.

| Param             | Type                                |
| ----------------- | ----------------------------------- |
| **`permissions`** | `SpeechRecognitionPluginPermission` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('end', ...)

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

Called when the speech recognizer has stopped listening.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'end'`      |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('error', ...)

```
addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs.

| Param              | Type                          |
| ------------------ | ----------------------------- |
| **`eventName`**    | `'error'`                     |
| **`listenerFunc`** | `(event: ErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('partialResult', ...)

```
addListener(eventName: 'partialResult', listenerFunc: (event: PartialResultEvent) => void) => Promise<PluginListenerHandle>
```

Called when a partial result is available.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'partialResult'`                     |
| **`listenerFunc`** | `(event: PartialResultEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('result', ...)

```
addListener(eventName: 'result', listenerFunc: (event: ResultEvent) => void) => Promise<PluginListenerHandle>
```

Called when the final results are available.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'result'`                     |
| **`listenerFunc`** | `(event: ResultEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('speechEnd', ...)

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

Called when the user has stopped speaking.

Only available on Android and Web.

| Param              | Type          |
| ------------------ | ------------- |
| **`eventName`**    | `'speechEnd'` |
| **`listenerFunc`** | `() => void`  |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('speechStart', ...)

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

Called when the user has started to speak.

Only available on Android and Web.

| Param              | Type            |
| ------------------ | --------------- |
| **`eventName`**    | `'speechStart'` |
| **`listenerFunc`** | `() => void`    |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('start', ...)

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

Called when the speech recognizer has started listening.

| Param              | Type         |
| ------------------ | ------------ |
| **`eventName`**    | `'start'`    |
| **`listenerFunc`** | `() => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('soundLevel', ...)

```
addListener(eventName: 'soundLevel', listenerFunc: (event: SoundLevelEvent) => void) => Promise<PluginListenerHandle>
```

Called when the sound level changes during speech recognition.

**Attention**: There is no guarantee that this method will be called.

Only available on Android and iOS.

| Param              | Type                               |
| ------------------ | ---------------------------------- |
| **`eventName`**    | `'soundLevel'`                     |
| **`listenerFunc`** | `(event: SoundLevelEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.5.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### GetLanguagesResult

| Prop            | Type       | Description                                                             | Since |
| --------------- | ---------- | ----------------------------------------------------------------------- | ----- |
| **`languages`** | `string[]` | The supported languages for speech recognition as BCP-47 language tags. | 6.0.0 |

#### GetOnDeviceLanguagesResult

| Prop                     | Type       | Description                                                                                                                                                       | Since |
| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`installedLanguages`** | `string[]` | The installed on-device languages as BCP-47 language tags.                                                                                                        | 8.1.0 |
| **`pendingLanguages`**   | `string[]` | The on-device languages whose download is scheduled or in progress as BCP-47 language tags. Only available on Android.                                            | 8.1.0 |
| **`supportedLanguages`** | `string[]` | The supported on-device languages as BCP-47 language tags. These languages can be downloaded for on-device use using the {@link downloadOnDeviceLanguage} method. | 8.1.0 |

#### DownloadOnDeviceLanguageOptions

| Prop           | Type     | Description                                           | Since |
| -------------- | -------- | ----------------------------------------------------- | ----- |
| **`language`** | `string` | The BCP-47 language tag for the language to download. | 8.1.0 |

#### DownloadOnDeviceLanguageCallbackEvent

| Prop            | Type      | Description                                             | Since |
| --------------- | --------- | ------------------------------------------------------- | ----- |
| **`progress`**  | `number`  | The download progress, as a percentage between 0 and 1. | 8.1.0 |
| **`completed`** | `boolean` | Whether the download is completed or not.               | 8.1.0 |

#### IsAvailableResult

| Prop              | Type      | Description                                                      | Since |
| ----------------- | --------- | ---------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not the speech recognizer is available on the device. | 6.0.0 |

#### IsListeningResult

| Prop              | Type      | Description                                                  | Since |
| ----------------- | --------- | ------------------------------------------------------------ | ----- |
| **`isListening`** | `boolean` | Whether or not the speech recognizer is currently listening. | 6.0.0 |

#### StartListeningOptions

| Prop                               | Type                   | Description                                                                                                                                                                                                                                                                                                                                                                                             | Default                        | Since |
| ---------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----- |
| **`audioSessionCategory`**         | `AudioSessionCategory` | The audio session category to use for speech recognition. Only available on iOS.                                                                                                                                                                                                                                                                                                                        | `AudioSessionCategory.Record`  | 7.2.0 |
| **`audioSessionMode`**             | `AudioSessionMode`     | The audio session mode for speech recognition. Only available on iOS.                                                                                                                                                                                                                                                                                                                                   | `AudioSessionMode.Measurement` | 8.1.0 |
| **`contextualStrings`**            | `string[]`             | An array of phrases that should be recognized, even if they are not in the system vocabulary. Only available on Android (SDK 33+) and iOS.                                                                                                                                                                                                                                                              |                                | 7.3.0 |
| **`deactivateAudioSessionOnStop`** | `boolean`              | Whether or not to deactivate your app's audio session on stop. Only available on iOS.                                                                                                                                                                                                                                                                                                                   | `true`                         | 7.2.0 |
| **`enableFormatting`**             | `boolean`              | Whether to add punctuation to speech recognition results. **Note**: On Android, this option does not work reliably as it varies depending on the device and TTS engine. Only available on Android (SDK 33+) and iOS (+16).                                                                                                                                                                              | `false`                        | 7.4.0 |
| **`language`**                     | `string`               | The BC-47 language tag for the language to use for speech recognition.                                                                                                                                                                                                                                                                                                                                  |                                | 6.0.0 |
| **`silenceThreshold`**             | `number`               | The number of milliseconds of silence before the speech recognition ends. **Attention**: This option may not work reliably on all devices and platforms as it depends on the underlying speech recognition service. This is a limitation of the platform and not the plugin itself. Continuous listening by setting an extremely high value will not work. Only available on Android (SDK 33+) and iOS. | `2000`                         | 6.0.0 |
| **`taskHint`**                     | `TaskHint`             | The type of task for which the speech recognition is being used for. Only available on iOS.                                                                                                                                                                                                                                                                                                             | `TaskHint.Unspecified`         | 7.5.0 |
| **`requireOnDeviceRecognition`**   | `boolean`              | Whether to require on-device speech recognition. If `true`, speech recognition will only use on-device models. If the on-device model is not available, the call will fail with an error. Only available on Android (SDK 33+) and iOS.                                                                                                                                                                  | `false`                        | 8.1.0 |
| **`useSpeechTranscriber`**         | `boolean`              | Whether to use the `SpeechTranscriber` API for on-device speech recognition. This avoids the "Speech data from this app will be sent to Apple" permission dialog and only requires microphone permission. On-device recognition is used implicitly when this option is set to `true`, so `requireOnDeviceRecognition` does not need to be set separately. Only available on iOS (26+).                  | `false`                        | 8.1.0 |

#### StopListeningOptions

| Prop                         | Type      | Description                                                                   | Default | Since |
| ---------------------------- | --------- | ----------------------------------------------------------------------------- | ------- | ----- |
| **`deactivateAudioSession`** | `boolean` | Whether or not to deactivate your app's audio session. Only available on iOS. | `true`  | 7.2.0 |

#### PermissionStatus

| Prop                    | Type              | Description                                                                 | Since |
| ----------------------- | ----------------- | --------------------------------------------------------------------------- | ----- |
| **`audioRecording`**    | `PermissionState` | Permission state for recording audio.                                       | 7.1.0 |
| **`recordAudio`**       | `PermissionState` | Permission state for speech recognition.                                    | 6.0.0 |
| **`speechRecognition`** | `PermissionState` | Permission state for speech recognition. Only available on Android and iOS. | 7.1.0 |

#### SpeechRecognitionPluginPermission

| Prop              | Type                                |
| ----------------- | ----------------------------------- |
| **`permissions`** | `SpeechRecognitionPermissionType[]` |

#### PluginListenerHandle

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

#### ErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 6.0.0 |

#### PartialResultEvent

| Prop         | Type     | Description                                   | Since |
| ------------ | -------- | --------------------------------------------- | ----- |
| **`result`** | `string` | The partial result of the speech recognition. | 6.0.0 |

#### ResultEvent

| Prop         | Type     | Description                                 | Since |
| ------------ | -------- | ------------------------------------------- | ----- |
| **`result`** | `string` | The final result of the speech recognition. | 6.0.0 |

#### SoundLevelEvent

| Prop        | Type     | Description                                                                                                                                                                          | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`level`** | `number` | The sound level of the audio signal. The value is normalized across platforms to a range of 0-100, where 0 represents minimum detected sound and 100 represents maximum sound level. | 7.5.0 |

### Type Aliases

#### DownloadOnDeviceLanguageCallback

`(event: DownloadOnDeviceLanguageCallbackEvent | null, error: any): void`

#### CallbackId

`string`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### SpeechRecognitionPermissionType

`'audioRecording' | 'speechRecognition'`

### Enums

#### AudioSessionCategory

| Members             | Value               | Description                                                           | Since |
| ------------------- | ------------------- | --------------------------------------------------------------------- | ----- |
| **`Record`**        | `'RECORD'`          | The category for recording audio while also silencing playback audio. | 7.2.0 |
| **`PlayAndRecord`** | `'PLAY_AND_RECORD'` | The category for recording (input) and playback (output) of audio.    | 7.2.0 |

#### AudioSessionMode

| Members              | Value               | Description                                                                   | Since |
| -------------------- | ------------------- | ----------------------------------------------------------------------------- | ----- |
| **`Default`**        | `'DEFAULT'`         | Default mode that doesn't enable additional audio session features.           | 8.1.0 |
| **`GameChat`**       | `'GAME_CHAT'`       | Mode for chat communication over VoIP or internet, optimized for low latency. | 8.1.0 |
| **`Measurement`**    | `'MEASUREMENT'`     | Mode for high-quality measurement recordings with maximum dynamic range.      | 8.1.0 |
| **`SpokenAudio`**    | `'SPOKEN_AUDIO'`    | Mode for speech recording and transcription with optimized voice processing.  | 8.1.0 |
| **`VideoChat`**      | `'VIDEO_CHAT'`      | Mode for two-way video chat communications.                                   | 8.1.0 |
| **`VideoRecording`** | `'VIDEO_RECORDING'` | Mode for recording video content with high-quality audio.                     | 8.1.0 |
| **`VoiceChat`**      | `'VOICE_CHAT'`      | Mode for voice chat communications.                                           | 8.1.0 |

#### TaskHint

| Members            | Value            | Since |
| ------------------ | ---------------- | ----- |
| **`Confirmation`** | `'CONFIRMATION'` | 7.5.0 |
| **`Dictation`**    | `'DICTATION'`    | 7.5.0 |
| **`Search`**       | `'SEARCH'`       | 7.5.0 |
| **`Unspecified`**  | `'UNSPECIFIED'`  | 7.5.0 |

## FAQ

### Why does `getLanguages` never resolve on some Android devices?

The `getLanguages()` method is unfortunately not supported by all Android devices. If the method is not supported, the promise will never resolve. It's therefore recommended to set a timeout for the promise and fall back to a predefined list of languages if the timeout is reached.

### Can I use this plugin for continuous speech recognition?

No, continuous listening is not supported. The `silenceThreshold` option controls how many milliseconds of silence end the recognition, but it depends on the underlying speech recognition service and setting an extremely high value will not keep the recognizer listening indefinitely. This is a limitation of the platforms and not of the plugin itself.

### How can I avoid the "Speech data will be sent to Apple" permission dialog?

Set the `useSpeechTranscriber` option of the `startListening(...)` method to `true`. This uses Apple's modern `SpeechTranscriber` API with fully on-device processing, so only the microphone permission is required and no speech recognition permission dialog is shown. This option is only available on iOS 26+.

### What is the difference between the `partialResult` and `result` events?

The `partialResult` event is emitted while the user is still speaking and delivers intermediate transcriptions, which is useful for displaying live feedback. The `result` event is emitted when the final results of the speech recognition are available.

### What permissions does this plugin require?

The plugin requires permission to record audio and, on iOS, permission to use speech recognition. On iOS, you must add the `NSSpeechRecognitionUsageDescription` and `NSMicrophoneUsageDescription` keys to your `Info.plist` file as described in the [Installation](#installation) section. You can check and request the permissions at runtime using the `checkPermissions()` and `requestPermissions(...)` methods.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play audio with background support.
- [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone.
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text (also known as text-to-speech).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-recognition/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-recognition/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-recognition/LICENSE).

# Capacitor Speech Synthesis Plugin

Capacitor plugin for synthesizing speech from text (also known as text-to-speech) with advanced features like voice selection, pitch, and rate control.

## Features

The Capacitor Speech Synthesis plugin offers one of the most feature-rich text-to-speech solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS and Web.
- 🌐 **Multiple Languages**: Supports many different languages.
- 🗣️ **Multiple Voices**: Supports multiple voices for each language.
- 🎚️ **Customization**: Customize the pitch, rate, volume and voice of the speech.
- 🎧 **Background Audio**: Synthesize speech from text while your application runs in the background.
- 📜 **Queue Strategy**: Add or flush the utterance to the queue.
- 🔊 **Events**: Listen for events like `boundary`, `end`, `error` and `start`.
- ⏸️ **Pause/Resume**: Pause and resume speech synthesis.
- ⚔️ **Battle-Tested**: Used in more than 100 projects.
- 🤝 **Compatibility**: Compatible with the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/), [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) and [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Speech Synthesis plugin is typically used whenever an app needs to read text aloud to the user, for example:

- **Read content aloud**: Read articles, messages, or notifications to users, for example while they are driving or exercising.
- **Voice feedback**: Give spoken confirmations or instructions in response to user actions, even while your app runs in the background.
- **Accessibility**: Make your app usable for people with visual impairments or reading difficulties by speaking on-screen content.
- **Language learning**: Demonstrate the pronunciation of words and sentences in many different languages and voices.
- **Audio file generation**: Synthesize speech to an audio file, for example to play it later or share it.

## 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     |

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-speech-synthesis` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-speech-synthesis
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to speak and synthesize text, pause and cancel speech, check availability, list languages and voices, and handle synthesis events.

### Speak a text

Add an utterance to the utterance queue to be spoken. You can customize the language, pitch, rate, voice, and volume. The `end` event is emitted when the utterance has finished:

```
import { SpeechSynthesis, QueueStrategy } from '@capawesome-team/capacitor-speech-synthesis';

const speak = async () => {
  // Add an utterance to the utterance queue to be spoken
  const { utteranceId } = await SpeechSynthesis.speak({
    language: 'en-US',
    pitch: 1.0,
    queueStrategy: QueueStrategy.Add,
    rate: 1.0,
    text: 'Hello, World!',
    voiceId: 'com.apple.ttsbundle.Samantha-compact',
    volume: 1.0,
  });
  // Wait for the utterance to finish
  await new Promise(resolve => {
    void SpeechSynthesis.addListener('end', event => {
      if (event.utteranceId === utteranceId) {
        resolve();
      }
    });
  });
};
```

### Synthesize speech to an audio file

Instead of speaking an utterance, you can synthesize it to an audio file, for example to play it later. The file is available as soon as the `end` event is emitted. Only available on Android and iOS:

```
import { SpeechSynthesis, QueueStrategy } from '@capawesome-team/capacitor-speech-synthesis';

const synthesizeToFile = async () => {
  // Add an utterance to the utterance queue to be synthesized to a file
  const { path, utteranceId } = await SpeechSynthesis.synthesizeToFile({
    language: 'en-US',
    pitch: 1.0,
    queueStrategy: QueueStrategy.Add,
    rate: 1.0,
    text: 'Hello, World!',
    voiceId: 'com.apple.ttsbundle.Samantha-compact',
    volume: 1.0,
  });
  // Wait for the utterance to finish
  await new Promise(resolve => {
    void SpeechSynthesis.addListener('end', event => {
      if (event.utteranceId === utteranceId) {
        resolve();
      }
    });
  });
  // Return the path to the synthesized audio file
  return path;
};
```

### Pause, resume, and cancel speech

Pause the speech immediately and resume it later, or remove all utterances from the utterance queue:

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const pause = async () => {
  await SpeechSynthesis.pause();
};

const resume = async () => {
  await SpeechSynthesis.resume();
};

const cancel = async () => {
  await SpeechSynthesis.cancel();
};
```

### Check availability

Check whether speech synthesis is available on the current device and whether a specific language or voice is supported:

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const isAvailable = async () => {
  const result = await SpeechSynthesis.isAvailable();
  return result.isAvailable;
};

const isLanguageAvailable = async () => {
  const result = await SpeechSynthesis.isLanguageAvailable({ language: 'en-US' });
  return result.isAvailable;
};

const isVoiceAvailable = async () => {
  const result = await SpeechSynthesis.isVoiceAvailable({ voiceId: 'com.apple.ttsbundle.Samantha-compact' });
  return result.isAvailable;
};
```

### Get the available languages and voices

Retrieve the available languages as BCP-47 language tags and the available voices, for example to let the user pick a preferred voice:

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const getLanguages = async () => {
  const result = await SpeechSynthesis.getLanguages();
  return result.languages;
};

const getVoices = async () => {
  const result = await SpeechSynthesis.getVoices();
  return result.voices;
};
```

### Listen for speech synthesis events

React to the different stages of the speech synthesis, for example to highlight the word that is currently being spoken using the `boundary` event:

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const addListeners = () => {
  SpeechSynthesis.addListener('boundary', (event) => {
    console.log('boundary', event);
  });

  SpeechSynthesis.addListener('end', (event) => {
    console.log('end', event);
  });

  SpeechSynthesis.addListener('error', (event) => {
    console.log('error', event);
  });

  SpeechSynthesis.addListener('start', (event) => {
    console.log('start', event);
  });
};
```

### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

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

## API

- [`activateAudioSession(...)`](#activateaudiosession)
- [`cancel()`](#cancel)
- [`deactivateAudioSession()`](#deactivateaudiosession)
- [`getLanguages()`](#getlanguages)
- [`getVoices()`](#getvoices)
- [`initialize()`](#initialize)
- [`isAvailable()`](#isavailable)
- [`isSpeaking()`](#isspeaking)
- [`isLanguageAvailable(...)`](#islanguageavailable)
- [`isVoiceAvailable(...)`](#isvoiceavailable)
- [`pause()`](#pause)
- [`resume()`](#resume)
- [`speak(...)`](#speak)
- [`synthesizeToFile(...)`](#synthesizetofile)
- [`addListener('boundary', ...)`](#addlistenerboundary-)
- [`addListener('end', ...)`](#addlistenerend-)
- [`addListener('error', ...)`](#addlistenererror-)
- [`addListener('start', ...)`](#addlistenerstart-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### activateAudioSession(...)

```
activateAudioSession(options: ActivateAudioSessionOptions) => Promise<void>
```

Activate the audio session. This method is not mandatory. It can be used to set the audio session category before speaking.

Only available on iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `ActivateAudioSessionOptions` |

**Since:** 6.0.0

______________________________________________________________________

### cancel()

```
cancel() => Promise<void>
```

Remove all utterances from the utterance queue.

**Since:** 6.0.0

______________________________________________________________________

### deactivateAudioSession()

```
deactivateAudioSession() => Promise<void>
```

Deactivate the audio session.

Only available on iOS.

**Since:** 6.0.0

______________________________________________________________________

### getLanguages()

```
getLanguages() => Promise<GetLanguagesResult>
```

Get the available languages for speech synthesis.

**Returns:** `Promise<GetLanguagesResult>`

**Since:** 6.0.0

______________________________________________________________________

### getVoices()

```
getVoices() => Promise<GetVoicesResult>
```

Get the available voices for speech synthesis.

**Returns:** `Promise<GetVoicesResult>`

**Since:** 6.0.0

______________________________________________________________________

### initialize()

```
initialize() => Promise<void>
```

Initialize the plugin before any other method is called.

Use this method to warm up the speech synthesis engine. If this method is not called, the plugin will be automatically initialized on the first call to any other method.

Only available on Android and iOS.

**Since:** 6.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if speech synthesis is available on the current device.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 6.0.0

______________________________________________________________________

### isSpeaking()

```
isSpeaking() => Promise<IsSpeakingResult>
```

Check if speech synthesis is currently speaking.

**Returns:** `Promise<IsSpeakingResult>`

**Since:** 6.0.0

______________________________________________________________________

### isLanguageAvailable(...)

```
isLanguageAvailable(options: IsLanguageAvailableOption) => Promise<IsLanguageAvailableResult>
```

Check if a language is available for speech synthesis.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `IsLanguageAvailableOption` |

**Returns:** `Promise<IsLanguageAvailableResult>`

**Since:** 6.0.0

______________________________________________________________________

### isVoiceAvailable(...)

```
isVoiceAvailable(options: IsVoiceAvailableOption) => Promise<IsVoiceAvailableResult>
```

Check if a voice is available for speech synthesis.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `IsVoiceAvailableOption` |

**Returns:** `Promise<IsVoiceAvailableResult>`

**Since:** 6.0.0

______________________________________________________________________

### pause()

```
pause() => Promise<void>
```

Pause speech immediately.

**Since:** 7.2.0

______________________________________________________________________

### resume()

```
resume() => Promise<void>
```

Resume speech.

**Since:** 7.2.0

______________________________________________________________________

### speak(...)

```
speak(options: SpeakOptions) => Promise<SpeakResult>
```

Add an utterance to the utterance queue to be spoken.

The `end` event will be emitted when the utterance has finished.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `SpeakOptions` |

**Returns:** `Promise<SpeakResult>`

**Since:** 6.0.0

______________________________________________________________________

### synthesizeToFile(...)

```
synthesizeToFile(options: SynthesizeToFileOptions) => Promise<SynthesizeToFileResult>
```

Add an utterance to the utterance queue to be synthesized to a file.

The `end` event will be emitted when the utterance has finished.

Only available on Android and iOS.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `SpeakOptions` |

**Returns:** `Promise<SynthesizeToFileResult>`

**Since:** 7.1.0

______________________________________________________________________

### addListener('boundary', ...)

```
addListener(eventName: 'boundary', listenerFunc: (event: BoundaryEvent) => void) => Promise<PluginListenerHandle>
```

Called hen the spoken utterance reaches a word boundary.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'boundary'`                     |
| **`listenerFunc`** | `(event: BoundaryEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('end', ...)

```
addListener(eventName: 'end', listenerFunc: (event: EndEvent) => void) => Promise<PluginListenerHandle>
```

Called when the spoken utterance has finished.

| Param              | Type                        |
| ------------------ | --------------------------- |
| **`eventName`**    | `'end'`                     |
| **`listenerFunc`** | `(event: EndEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('error', ...)

```
addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during speech synthesis.

| Param              | Type                          |
| ------------------ | ----------------------------- |
| **`eventName`**    | `'error'`                     |
| **`listenerFunc`** | `(event: ErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('start', ...)

```
addListener(eventName: 'start', listenerFunc: (event: StartEvent) => void) => Promise<PluginListenerHandle>
```

Called when the spoken utterance has started.

| Param              | Type                          |
| ------------------ | ----------------------------- |
| **`eventName`**    | `'start'`                     |
| **`listenerFunc`** | `(event: StartEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for the plugin.

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### ActivateAudioSessionOptions

| Prop           | Type                   | Description                        | Since |
| -------------- | ---------------------- | ---------------------------------- | ----- |
| **`category`** | `AudioSessionCategory` | The audio session category to set. | 6.0.0 |

#### GetLanguagesResult

| Prop            | Type       | Description                                     | Since |
| --------------- | ---------- | ----------------------------------------------- | ----- |
| **`languages`** | `string[]` | The available languages as BC-47 language tags. | 6.0.0 |

#### GetVoicesResult

| Prop         | Type      | Description           | Since |
| ------------ | --------- | --------------------- | ----- |
| **`voices`** | `Voice[]` | The available voices. | 6.0.0 |

#### Voice

| Prop                              | Type       | Description                                                           | Since                                           |
| --------------------------------- | ---------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| **`default`**                     | `boolean`  | Whether or not the voice is the default voice. Only available on Web. | 6.0.0                                           |
| **`gender`**                      | \`'female' | 'male'\`                                                              | The gender of the voice. Only available on iOS. |
| **`id`**                          | `string`   | The identifier of the voice.                                          | 6.0.0                                           |
| **`isNetworkConnectionRequired`** | `boolean`  | Whether or not the voice is available via a local or remote service.  | 6.0.0                                           |
| **`language`**                    | `string`   | The BC-47 language tag for the language of the voice.                 | 6.0.0                                           |
| **`name`**                        | `string`   | The name of the voice.                                                | 6.0.0                                           |

#### IsAvailableResult

| Prop              | Type      | Description                                                         | Since |
| ----------------- | --------- | ------------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not speech synthesis is available on the current device. | 6.0.0 |

#### IsSpeakingResult

| Prop             | Type      | Description                                            | Since |
| ---------------- | --------- | ------------------------------------------------------ | ----- |
| **`isSpeaking`** | `boolean` | Whether or not an utterance is currently being spoken. | 6.0.0 |

#### IsLanguageAvailableResult

| Prop              | Type      | Description                                                    | Since |
| ----------------- | --------- | -------------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not the language is available for speech synthesis. | 6.0.0 |

#### IsLanguageAvailableOption

| Prop           | Type     | Description                                       | Since |
| -------------- | -------- | ------------------------------------------------- | ----- |
| **`language`** | `string` | The BC-47 language tag for the language to check. | 6.0.0 |

#### IsVoiceAvailableResult

| Prop              | Type      | Description                                                 | Since |
| ----------------- | --------- | ----------------------------------------------------------- | ----- |
| **`isAvailable`** | `boolean` | Whether or not the voice is available for speech synthesis. | 6.0.0 |

#### IsVoiceAvailableOption

| Prop          | Type     | Description                           | Since |
| ------------- | -------- | ------------------------------------- | ----- |
| **`voiceId`** | `string` | The identifier of the voice to check. | 6.0.0 |

#### SpeakResult

| Prop              | Type     | Description                                           | Since |
| ----------------- | -------- | ----------------------------------------------------- | ----- |
| **`utteranceId`** | `string` | The identifier of the utterance that is being spoken. | 6.0.0 |

#### SpeakOptions

| Prop                       | Type                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                            | Since |
| -------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----- |
| **`audioSessionCategory`** | `AudioSessionCategory` | The audio session category to use for speech synthesis. The audio session will be automatically activated with this category when speech starts and deactivated when speech ends, restoring the previous audio session state. With the `PLAYBACK`, `PLAY_AND_RECORD` and `MULTI_ROUTE` categories, audio from other apps (e.g. music) is ducked (volume reduced) while speaking and restored afterwards. With the default `SOLO_AMBIENT` category, audio from other apps is interrupted. Only available on iOS. | `AudioSessionCategory.SoloAmbient` | 8.0.0 |
| **`language`**             | `string`               | The BC-47 language tag for the language to use for speech synthesis. On **iOS**, this option is only used when the `voiceId` option is not provided.                                                                                                                                                                                                                                                                                                                                                            |                                    | 6.0.0 |
| **`pitch`**                | `number`               | The pitch that the utterance will be spoken at.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `1.0`                              | 6.0.0 |
| **`queueStrategy`**        | `QueueStrategy`        | The queue strategy to use for the utterance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `QueueStrategy.Add`                | 6.0.0 |
| **`rate`**                 | `number`               | The speed at which the utterance will be spoken at.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `1.0`                              | 6.0.0 |
| **`text`**                 | `string`               | The text that will be synthesized when the utterance is spoken.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                    | 6.0.0 |
| **`voiceId`**              | `string`               | The identifier of the voice to use for speech synthesis.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                                    | 6.0.0 |
| **`volume`**               | `number`               | The volume that the utterance will be spoken at.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `1.0`                              | 6.0.0 |

#### SynthesizeToFileResult

| Prop       | Type     | Description                                                                                                                                                 | Since |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The path to which the synthesized audio file will be saved. The file is available as soon as the `end` event is emitted. Only available on Android and iOS. | 7.1.0 |

#### PluginListenerHandle

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

#### BoundaryEvent

| Prop              | Type     | Description                                           | Since |
| ----------------- | -------- | ----------------------------------------------------- | ----- |
| **`endIndex`**    | `number` | The index of the last character in the word.          | 6.0.0 |
| **`startIndex`**  | `number` | The index of the first character in the word.         | 6.0.0 |
| **`utteranceId`** | `string` | The identifier of the utterance that is being spoken. | 6.0.0 |
| **`word`**        | `string` | The word that was spoken.                             | 6.0.0 |

#### EndEvent

| Prop              | Type     | Description                                        | Since |
| ----------------- | -------- | -------------------------------------------------- | ----- |
| **`utteranceId`** | `string` | The identifier of the utterance that has finished. | 6.0.0 |

#### ErrorEvent

| Prop              | Type     | Description                                            | Since |
| ----------------- | -------- | ------------------------------------------------------ | ----- |
| **`message`**     | `string` | The error message.                                     | 6.0.0 |
| **`utteranceId`** | `string` | The identifier of the utterance that caused the error. | 6.0.0 |

#### StartEvent

| Prop              | Type     | Description                                       | Since |
| ----------------- | -------- | ------------------------------------------------- | ----- |
| **`utteranceId`** | `string` | The identifier of the utterance that has started. | 6.0.0 |

### Type Aliases

#### SynthesizeToFileOptions

`SpeakOptions`

### Enums

#### AudioSessionCategory

| Members             | Value               | Description                                                                                                                                         | Since |
| ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Ambient`**       | `'AMBIENT'`         | The audio session category for ambient sound. Audio from other apps mixes with your audio. Screen locking and the Silent switch silence your audio. | 6.0.0 |
| **`MultiRoute`**    | `'MULTI_ROUTE'`     | The audio session category for routing distinct streams to different outputs.                                                                       | 8.0.0 |
| **`PlayAndRecord`** | `'PLAY_AND_RECORD'` | The audio session category for recording or playback.                                                                                               | 8.0.0 |
| **`Playback`**      | `'PLAYBACK'`        | The audio session category for playback. App audio continues with the Silent switch set to silent or when the screen locks.                         | 6.0.0 |
| **`Record`**        | `'RECORD'`          | The audio session category for recording.                                                                                                           | 8.0.0 |
| **`SoloAmbient`**   | `'SOLO_AMBIENT'`    | The default audio session category. Audio from other apps is silenced. Screen locking and the Silent switch silence your audio.                     | 8.0.0 |

#### QueueStrategy

| Members     | Value | Description                                                          | Since |
| ----------- | ----- | -------------------------------------------------------------------- | ----- |
| **`Add`**   | `0`   | Add the utterance to the end of the queue.                           | 6.0.0 |
| **`Flush`** | `1`   | Flush the queue and add the utterance to the beginning of the queue. | 6.0.0 |

## FAQ

### How do I know when an utterance has finished?

The `speak(...)` and `synthesizeToFile(...)` methods resolve as soon as the utterance has been added to the utterance queue, not when it has finished. To be notified when the utterance has finished, add a listener for the `end` event and compare the `utteranceId` of the event with the one returned by the method, as shown in the [usage example](#speak-a-text) above.

### Why is no audio played when my iPhone is in silent mode?

By default, the plugin uses the `SoloAmbient` audio session category on iOS, which is silenced by the Silent switch and when the screen locks. If the speech should continue to play in silent mode or when the screen locks, set the `audioSessionCategory` option of the `speak(...)` method to `AudioSessionCategory.Playback`.

### Can I save the synthesized speech as an audio file?

Yes, use the `synthesizeToFile(...)` method to synthesize an utterance to an audio file instead of speaking it. The result contains the path to which the file is saved, and the file is available as soon as the `end` event is emitted. This method is only available on Android and iOS.

### How do I use a specific voice?

First, retrieve the available voices using the `getVoices()` method. Then pass the identifier of the desired voice as the `voiceId` option to the `speak(...)` method. Note that on iOS, the `language` option is only used when the `voiceId` option is not provided.

### What is the difference between the `Add` and `Flush` queue strategies?

The `QueueStrategy.Add` strategy adds the utterance to the end of the utterance queue, so it is spoken after all previously queued utterances. The `QueueStrategy.Flush` strategy flushes the queue and adds the utterance to the beginning of the queue, so it is spoken as soon as possible.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play audio with background support.
- [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone.
- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/): Transcribe speech into text (also known as speech-to-text).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-synthesis/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-synthesis/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/speech-synthesis/LICENSE).

# Capacitor SQLite Plugin

Capacitor plugin to access SQLite databases with support for encryption, transactions, and schema migrations.[1](#fn:1)[2](#fn:2)[3](#fn:3)

## Features

The Capacitor SQLite plugin is one of the most complete local database solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, Web and Electron.
- 🔒 **Encryption**: Supports 256 bit AES encryption with custom keys.
- 📦 **Bundled SQLite**: Opt-in bundling of the latest SQLite version.
- 🧩 **Custom Extensions**: Load app-bundled SQLite extensions on Android.
- 📖 **Read-only mode**: Open databases in read-only mode to prevent modifications.
- 📂 **File-based**: Open existing databases or create new ones with a file path.
- 💾 **In-memory databases**: Create temporary in-memory databases for quick operations or testing.
- 📈 **Schema migrations**: Automatically apply schema migrations when opening a database.
- 🔄 **Transactions**: Supports transactions with `beginTransaction(...)`, `commitTransaction(...)`, and `rollbackTransaction(...)`.
- 🔍 **Querying**: Execute SQL queries with `query(...)` and `execute(...)`.
- 🔢 **Data Types**: Supports all SQLite data types: `NULL`, `INTEGER`, `REAL`, `TEXT`, and `BLOB`.
- 🛡️ **Prepared Statements**: Uses prepared statements to prevent SQL injection attacks.
- 🕸️ **SQLite WASM**: Uses SQLite WebAssembly for web platform support.
- ⚛️ **Electron Native**: Uses native SQLite for Electron via the `node:sqlite` module.
- 📝 **Full Text Search**: Supports full text search with [FTS5](https://www.sqlite.org/fts5.html).
- 🗄️ **Key-Value Store**: Built-in [key-value store](#key-value-store) for simple data persistence without SQL.
- 🗃️ **ORM Support**: Works with popular ORMs like [Drizzle](#drizzle), [Kysely](#kysely) and [TypeORM](#typeorm).
- 🤝 **Compatibility**: Compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll add it for you!

## Use Cases

The SQLite plugin is typically used whenever an app needs a robust local database, for example:

- **Offline-first apps**: Store structured records locally so the app remains fully functional without a network connection.
- **Encrypted data storage**: Protect sensitive records with 256 bit AES encryption using a custom encryption key.
- **Complex queries**: Filter, join, and aggregate large datasets with SQL instead of loading everything into memory.
- **Full text search**: Search large amounts of text quickly using the FTS5 extension.
- **Settings and session data**: Persist small key/value data with the built-in key-value store without writing any SQL.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.4.x          | >=8.x.x           | Active support |
| 0.3.x          | >=8.x.x           | Deprecated     |
| 0.2.x          | >=8.x.x           | Deprecated     |
| 0.1.x          | 7.x.x             | Deprecated     |

## Demo

Working examples can be found here:

- [capawesome-team/capacitor-sqlite-angular-demo](https://github.com/capawesome-team/capacitor-sqlite-angular-demo)
- [capawesome-team/capacitor-sqlite-react-demo](https://github.com/capawesome-team/capacitor-sqlite-react-demo)

## Guides

- [Alternative to the Capacitor Community SQLite plugin](https://capawesome.io/blog/alternative-to-capacitor-community-sqlite-plugin/)
- [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/)
- [Announcing the SQLite Plugin for Capacitor](https://capawesome.io/blog/announcing-the-capacitor-sqlite-plugin/)
- [Encrypting SQLite databases in Capacitor](https://capawesome.io/blog/encrypting-capacitor-sqlite-database/)
- [Exploring the Capacitor SQLite API](https://capawesome.io/blog/exploring-the-capacitor-sqlite-api/)
- [How to Use Drizzle ORM with Capacitor and SQLite](https://capawesome.io/blog/how-to-use-drizzle-orm-with-capacitor-and-sqlite/)
- [How to Use Kysely with Capacitor and SQLite](https://capawesome.io/blog/how-to-use-kysely-with-capacitor-and-sqlite/)
- [How to Use TypeORM with Capacitor and SQLite](https://capawesome.io/blog/how-to-use-typeorm-with-capacitor-and-sqlite/)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-sqlite` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-sqlite @sqlite.org/sqlite-wasm
npx cap sync
```

### Android

#### Encryption

If you want to use encryption, you must include the SQLCipher dependency in your app's `variables.gradle` file by setting the `capawesomeCapacitorSqliteIncludeSqlcipher` variable to `true`:

```
ext {
+  capawesomeCapacitorSqliteIncludeSqlcipher = true // Default: false
}
```

**Attention**: When using SQLCipher you are responsible for compliance with all export, re-export and import restrictions and regulations in all applicable countries. You can find more information about this in this [blog post](https://discuss.zetetic.net/t/export-requirements-for-applications-using-sqlcipher/47).

**Attention**: SQLCipher's Community Edition license requires that the SQLCipher copyright notice and BSD-style license text be reproduced in a **user-accessible location** within your application — for example, an "About" or "Licensing" screen, or in product documentation linked from the application. See the [SQLCipher license](https://www.zetetic.net/sqlcipher/license/) for the full text.

#### Bundled SQLite

By default, this plugin uses the system SQLite version provided by the Android device. If you want to use a newer, consistent SQLite version across all devices, you can opt in to bundling [requery/sqlite-android](https://github.com/requery/sqlite-android) by setting the `capawesomeCapacitorSqliteIncludeRequery` variable to `true` in your app's `variables.gradle` file:

```
ext {
+  capawesomeCapacitorSqliteIncludeRequery = true // Default: false
}
```

**Attention**: This option cannot be combined with `capawesomeCapacitorSqliteIncludeSqlcipher`. SQLCipher already bundles its own SQLite version.

You also need to add the JitPack repository to your app's `build.gradle` file:

```
repositories {
    google()
    mavenCentral()
+   maven { url 'https://jitpack.io' }
}
```

#### Custom Extensions

You can load app-bundled SQLite extensions when opening a database using the `androidExtensions` option of the `open(...)` method. This requires the bundled SQLite backend to be enabled (see [Bundled SQLite](#bundled-sqlite)), because the system SQLite version does not support loading extensions.

The extension libraries (`.so` files) must be bundled with your app for each supported ABI. The `name` of an extension is resolved to the corresponding native library, e.g. `sqlite_tokenizer_ar` resolves to `libsqlite_tokenizer_ar.so`.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$androidxSqliteVersion` version of `androidx.sqlite:sqlite` (default: `2.6.2`)
- `$androidxSqliteFrameworkAndroidVersion` version of `androidx.sqlite:sqlite-framework-android` (default: `2.6.2`)
- `$netZeteticSqlcipherVersion` version of `net.zetetic:sqlcipher-android` (default: `4.12.0`)
- `$requeryVersion` version of `com.github.requery:sqlite-android` (default: `3.49.0`)

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

### iOS

#### CocoaPods

Add the `Plain` pod to your app's `Podfile`:

```
target 'App' do
capacitor_pods
# Add your Pods here
+  pod 'CapawesomeTeamCapacitorSqlite/Plain', :path => '../../node_modules/@capawesome-team/capacitor-sqlite'
end
```

If you want to use encryption, add the `SQLCipher` pod instead:

```
target 'App' do
capacitor_pods
# Add your Pods here
- pod 'CapawesomeTeamCapacitorSqlite/Plain', :path => '../../node_modules/@capawesome-team/capacitor-sqlite'
+  pod 'CapawesomeTeamCapacitorSqlite/SQLCipher', :path => '../../node_modules/@capawesome-team/capacitor-sqlite'
end
```

**Attention**: Do not add the pod in the section `def capacitor_pods`, but under the comment `# Add your Pods here`.

**Attention**: When using SQLCipher you are responsible for compliance with all export, re-export and import restrictions and regulations in all applicable countries. You can find more information about this in this [blog post](https://discuss.zetetic.net/t/export-requirements-for-applications-using-sqlcipher/47).

**Attention**: SQLCipher's Community Edition license requires that the SQLCipher copyright notice and BSD-style license text be reproduced in a **user-accessible location** within your application — for example, an "About" or "Licensing" screen, or in product documentation linked from the application. See the [SQLCipher license](https://www.zetetic.net/sqlcipher/license/) for the full text.

#### Swift Package Manager

No additional setup is required for SPM.

By default, this plugin uses the system SQLite version provided by iOS. If you want to use a newer, consistent SQLite version across all iOS versions, you can opt in to bundling [CSQLite](https://github.com/stephencelis/CSQLite) (with FTS5 enabled) by enabling the `BundledSQLite` package trait. Add the following to your `capacitor.config.json` (or `capacitor.config.ts`):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capawesome-team/capacitor-sqlite": ["BundledSQLite"]
        }
      }
    }
  }
}
```

**Attention**: SPM trait support requires Capacitor CLI 8.3.0+ and Xcode 16.3+ (Swift 6.1+).

If you want to use encryption, you must enable the `SQLCipher` package trait instead:

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capawesome-team/capacitor-sqlite": ["SQLCipher"]
        }
      }
    }
  }
}
```

**Attention**: This trait cannot be combined with `BundledSQLite`. SQLCipher already bundles its own SQLite version.

**Attention**: When using SQLCipher you are responsible for compliance with all export, re-export and import restrictions and regulations in all applicable countries. You can find more information about this in this [blog post](https://discuss.zetetic.net/t/export-requirements-for-applications-using-sqlcipher/47).

**Attention**: SQLCipher's Community Edition license requires that the SQLCipher copyright notice and BSD-style license text be reproduced in a **user-accessible location** within your application — for example, an "About" or "Licensing" screen, or in product documentation linked from the application. See the [SQLCipher license](https://www.zetetic.net/sqlcipher/license/) for the full text.

#### Custom Extensions

If you want to use custom SQLite extensions, you must **statically link** them into your app and register them at startup, after which they are automatically available in every database opened by the plugin. This is required because iOS does not support loading extensions at runtime.

First, add the extension's C source file to your app target in Xcode and set the per-file compiler flag `-DSQLITE_CORE` (in **Build Phases › Compile Sources**). Then declare its entry point in your bridging header:

```
#include <sqlite3.h>

int sqlite3_myextension_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi);
```

Finally, register the extension before any database is opened, e.g. in your `AppDelegate`:

```
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  sqlite3_auto_extension(unsafeBitCast(sqlite3_myextension_init, to: (@convention(c) () -> Void).self))
  return true
}
```

The entry point name must follow the SQLite naming convention `sqlite3_<name>_init` and the extension must be compiled with `-DSQLITE_CORE` so that it links against the host SQLite. See [Run-Time Loadable Extensions](https://www.sqlite.org/loadext.html#statically_linking_a_run_time_loadable_extension) for details.

### Web

This plugin uses the [@sqlite.org/sqlite-wasm](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm) package to provide SQLite support on the web platform. It will automatically load the SQLite WASM module when needed. By default, databases are stored via the `opfs` VFS, which requires the page to be cross-origin isolated, so your server must send the COOP/COEP headers shown below. If you cannot send these headers, see [Can I use the plugin on the web without the COOP/COEP headers?](#can-i-use-the-plugin-on-the-web-without-the-coopcoep-headers).

#### Usage with Angular

If you are using Angular, you need to add the following configuration to your `angular.json` file to ensure the SQLite WASM module is copied to the assets folder during the build process and to set the necessary headers for the web worker:

```
{
  "projects": {
    "your-app-name": {
      "architect": {
        "build": {
          "options": {
            "assets": [
+              {
+                "glob": "**/*",
+                "input": "node_modules/@sqlite.org/sqlite-wasm/dist/",
+                "output": "/assets/sqlite-wasm/"
+              }
            ]
          }
        },
        "serve": {
+          "options": {
+            "headers": {
+              "Cross-Origin-Embedder-Policy": "require-corp",
+              "Cross-Origin-Opener-Policy": "same-origin"
+            }
+          }
        }
      }
    }
  }
}
```

Finally, you need to initialize the SQLite WASM module before using the plugin. You can do this in your `main.ts` file or in a service that is loaded at the start of your application:

```
import { Capacitor } from '@capacitor/core';
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const initialize = async () => {
  const isWeb = Capacitor.getPlatform() === 'web';
  if (isWeb) {
    // Initialize the SQLite WASM module
    await Sqlite.initialize({
      worker: new Worker('/assets/sqlite-wasm/sqlite3-worker1.mjs', { type: 'module' })
    });
  }
};
```

#### Usage with Vite

If you are using Vite, you need to add the following configuration to your `vite.config.ts` file to ensure the SQLite WASM module is loaded correctly:

```
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    exclude: ['@sqlite.org/sqlite-wasm'],
  },
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});
```

#### Data persistence

On the web platform, the database is stored in the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system), which is subject to the browser's storage eviction rules. By default, storage is granted on a best-effort basis: Chromium-based browsers and Firefox only evict data under storage pressure, but Safari deletes all script-writable storage (including the database) after seven days without user interaction if the app runs in a browser tab. Web apps added to the home screen are exempt from this rule.

To reduce the risk of eviction, request persistent storage with [`navigator.storage.persist()`](https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist). The timing of this call matters: browsers grant persistence based on engagement heuristics, and Firefox shows a permission prompt. You should therefore call it at a moment of meaningful user engagement (for example, after sign-in or after the user has saved data for the first time) instead of on the first page load:

```
import { Capacitor } from '@capacitor/core';

const requestPersistentStorage = async () => {
  if (Capacitor.getPlatform() === 'web' && navigator.storage?.persist) {
    const persisted = await navigator.storage.persisted();
    if (!persisted) {
      await navigator.storage.persist();
    }
  }
};
```

Note that persistence is granted at the browser's discretion and applies to the entire origin's storage, not just the database. It reduces the risk of eviction but is not an absolute guarantee. On Android and iOS, the database is stored in the app's sandbox and is not affected by these rules.

#### Debugging

You can inspect the SQLite database stored in OPFS using the [OPFS Explorer](https://chromewebstore.google.com/detail/opfs-explorer/acndjpgkpaclldomagafnognkcgjignd) Chrome DevTools extension.

### Electron

This plugin uses the Node.js `node:sqlite` module to provide native SQLite support on Electron. The `node:sqlite` module is available starting from Node.js 22.5.0 (Electron 33+).

#### Database Storage

By default, databases are stored directly in Electron's `userData` directory:

- **Windows**: `%APPDATA%\YourAppName\`
- **macOS**: `~/Library/Application Support/YourAppName/`
- **Linux**: `~/.config/YourAppName/`

You can organize databases into subfolders by including the subfolder path in the `path` parameter:

```
// Open database directly in userData directory
const { databaseId } = await Sqlite.open({
  path: 'mydb.db'
});

// Open database in a subfolder
const { databaseId } = await Sqlite.open({
  path: 'app/mydb.db'
});

// Open database from absolute path
const { databaseId } = await Sqlite.open({
  path: '/Users/username/Databases/MyApp/mydb.db'
});

// Open in-memory database
const { databaseId } = await Sqlite.open();
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to open and close a database, execute statements, query data, run transactions, change the encryption key, read the SQLite version, reclaim space, and handle errors.

### Open or create a database

Open an existing database or create a new one at the given path. You can optionally provide an encryption key (only available on Android and iOS) and schema migrations that are applied automatically when the database is opened:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const open = async () => {
  const { databaseId } = await Sqlite.open({
    encryptionKey: 'secret', // Tip: Use the Secure Preferences plugin to store the key securely
    readOnly: false,
    path: 'mydb.sqlite3',
    upgradeStatements: [
      {
        version: 1,
        statements: [
          'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
        ],
      },
      {
        version: 2,
        statements: ['ALTER TABLE users ADD COLUMN email TEXT'],
      },
    ],
    version: 2,
  });
};
```

### Execute a statement

Execute a single SQL statement such as `INSERT`, `UPDATE`, `DELETE`, or `CREATE TABLE`. Use placeholders to bind values and prevent SQL injection attacks:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const execute = async () => {
  const { databaseId } = await Sqlite.open();
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, age) VALUES (?, ?)',
    values: ['Alice', 30],
  });
};
```

### Query data

Execute a `SELECT` statement and retrieve the result set:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const query = async () => {
  const { databaseId } = await Sqlite.open();
  const result = await Sqlite.query({
    databaseId,
    statement: 'SELECT * FROM users WHERE age > ?',
    values: [25],
  });
  console.log(result.columns); // The column names in the result set
  console.log(result.rows); // The rows returned by the query
};
```

### Perform a transaction

Group multiple statements into a transaction so that they are either all committed or all rolled back:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const performTransaction = async () => {
  const { databaseId } = await Sqlite.open();
  await Sqlite.beginTransaction({ databaseId });
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, age) VALUES (?, ?)',
    values: ['Alice', 30],
  });
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, age) VALUES (?, ?)',
    values: ['Bob', 25],
  });
  await Sqlite.commitTransaction({ databaseId });
};
```

### Close the database

Close the database when it is no longer needed:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const close = async () => {
  const { databaseId } = await Sqlite.open();
  await Sqlite.close({ databaseId });
};
```

### Change the encryption key

Change the encryption key of an encrypted database. The database must first be opened with the current encryption key. Only available on Android and iOS:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const changeEncryptionKey = async () => {
  // Open the database with the old encryption key
  const { databaseId } = await Sqlite.open({
    encryptionKey: 'old-secret',
  });
  // Change the encryption key to a new one
  await Sqlite.changeEncryptionKey({
    databaseId,
    encryptionKey: 'new-secret',
  });
};
```

### Get the SQLite version

Get the version of the SQLite library used by the plugin:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const getVersion = async () => {
  const result = await Sqlite.getVersion();
  console.log(result.version); // The version of the SQLite library used by the plugin
};
```

### Reclaim unused space

Run the `VACUUM` command to rebuild the database file and optimize its size:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const vacuum = async () => {
  const { databaseId } = await Sqlite.open();
  await Sqlite.vacuum({ databaseId });
};
```

### Handle errors

Errors that originate from SQLite expose the SQLite result code in the `data.sqliteCode` property (see [Error Handling](#error-handling)):

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const handleErrors = async () => {
  try {
    await Sqlite.open({ path: '/invalid/path/to.db' });
  } catch (error) {
    // `error.data.sqliteCode` contains the SQLite result code (e.g. `14` for `SQLITE_CANTOPEN`)
    console.error(error.message, error.data?.sqliteCode);
  }
};
```

## API

- [`beginTransaction(...)`](#begintransaction)
- [`changeEncryptionKey(...)`](#changeencryptionkey)
- [`close(...)`](#close)
- [`closeAll()`](#closeall)
- [`commitTransaction(...)`](#committransaction)
- [`execute(...)`](#execute)
- [`getVersion()`](#getversion)
- [`initialize(...)`](#initialize)
- [`open(...)`](#open)
- [`query(...)`](#query)
- [`rollbackTransaction(...)`](#rollbacktransaction)
- [`vacuum(...)`](#vacuum)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### beginTransaction(...)

```
beginTransaction(options: BeginTransactionOptions) => Promise<void>
```

Begin a transaction on the specified database.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `BeginTransactionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### changeEncryptionKey(...)

```
changeEncryptionKey(options: ChangeEncryptionKeyOptions) => Promise<void>
```

Change the encryption key of the database.

**Attention**: This must be called after opening the database with the current encryption key.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `ChangeEncryptionKeyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### close(...)

```
close(options: CloseOptions) => Promise<void>
```

Close the specified database.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `CloseOptions` |

**Since:** 0.1.0

______________________________________________________________________

### closeAll()

```
closeAll() => Promise<void>
```

Close all databases that are currently open.

This is useful if the database identifiers are no longer available, for example after the web app has been reloaded.

**Since:** 0.3.10

______________________________________________________________________

### commitTransaction(...)

```
commitTransaction(options: CommitTransactionOptions) => Promise<void>
```

Commit the current transaction on the specified database.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `CommitTransactionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### execute(...)

```
execute(options: ExecuteOptions) => Promise<ExecuteResult>
```

Execute a single SQL statement on the specified database.

This method can be used to execute any SQL statement, including `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE`.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ExecuteOptions` |

**Returns:** `Promise<ExecuteResult>`

**Since:** 0.1.0

______________________________________________________________________

### getVersion()

```
getVersion() => Promise<GetVersionResult>
```

Get the version of the SQLite library used by the plugin.

To get the version of the database schema, simply run the `PRAGMA user_version;` command.

**Returns:** `Promise<GetVersionResult>`

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

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

Initialize the plugin before any other method is called.

Use this method to customize the plugin's behavior. If this method is not called, the plugin will be automatically initialized with default settings on the first call to any other method.

On **Android** and **iOS**, this method is a no-op.

On **Web**, this method allows you to pass a `Worker` instance that will be used for the SQLite WebAssembly initialization and to choose the VFS that stores the databases.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.3

______________________________________________________________________

### open(...)

```
open(options?: OpenOptions | undefined) => Promise<OpenResult>
```

Open a database with the specified options.

This method can be used to open an existing database or create a new one.

If `upgradeStatements` or `version` is provided, the pending upgrade statements are applied in a single transaction and `user_version` is never lowered.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `OpenOptions` |

**Returns:** `Promise<OpenResult>`

**Since:** 0.1.0

______________________________________________________________________

### query(...)

```
query(options: QueryOptions) => Promise<QueryResult>
```

Query the database and return the result set.

This method can be used to execute `SELECT` statements and retrieve the result set.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `QueryOptions` |

**Returns:** `Promise<QueryResult>`

**Since:** 0.1.0

______________________________________________________________________

### rollbackTransaction(...)

```
rollbackTransaction(options: RollbackTransactionOptions) => Promise<void>
```

Rollback the current transaction on the specified database.

This method will undo all changes made in the current transaction.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `RollbackTransactionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### vacuum(...)

```
vacuum(options: VacuumOptions) => Promise<void>
```

Runs the [VACUUM](https://www.sqlite.org/lang_vacuum.html) command to rebuild the database file.

This command can be used to reclaim unused space and optimize the database file.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `VacuumOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### BeginTransactionOptions

| Prop             | Type     | Description                                                       | Since |
| ---------------- | -------- | ----------------------------------------------------------------- | ----- |
| **`databaseId`** | `string` | The unique identifier for the database to begin a transaction on. | 0.1.0 |

#### ChangeEncryptionKeyOptions

| Prop                | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Since |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`databaseId`**    | `string` | The unique identifier for the database to change the encryption key for.                                                                                                                                                                                                                                                                                                                                                                                    | 0.1.0 |
| **`encryptionKey`** | `string` | The new encryption key to set for the database. **Attention:** It's recommended to use a strong encryption key to protect sensitive data. This key should be kept secret and not hard-coded in your application. If you lose the encryption key, you will not be able to access the data in the database. **Tip:** Use the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin to securely store the encryption key. | 0.1.0 |

#### CloseOptions

| Prop             | Type     | Description                                      | Since |
| ---------------- | -------- | ------------------------------------------------ | ----- |
| **`databaseId`** | `string` | The unique identifier for the database to close. | 0.1.0 |

#### CommitTransactionOptions

| Prop             | Type     | Description                                                        | Since |
| ---------------- | -------- | ------------------------------------------------------------------ | ----- |
| **`databaseId`** | `string` | The unique identifier for the database to commit a transaction on. | 0.1.0 |

#### ExecuteResult

| Prop          | Type     | Description                                                                                                         | Since |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ----- |
| **`changes`** | `number` | The number of rows modified by the statement. This property is set for `INSERT`, `UPDATE`, and `DELETE` statements. | 0.1.1 |
| **`rowId`**   | `number` | The row ID of the last inserted row. This property is only set when executing an `INSERT` statement.                | 0.1.1 |

#### ExecuteOptions

| Prop                | Type      | Description                                                                                                                                                                   | Default | Since |
| ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`databaseId`**    | `string`  | The unique identifier for the database to execute the statement on.                                                                                                           |         | 0.1.0 |
| **`returnChanges`** | `boolean` | Whether to return the number of rows modified by the statement. Disabling this option can improve performance for statements that do not require the number of modified rows. | `true`  | 0.1.2 |
| **`returnRowId`**   | `boolean` | Whether to return the row ID of the last inserted row. Disabling this option can improve performance for statements that do not require the row ID of the last inserted row.  | `true`  | 0.1.2 |
| **`statement`**     | `string`  | The SQL statement to execute. This can be any valid SQL statement, such as `INSERT`, `UPDATE`, `DELETE`, or `CREATE TABLE`.                                                   |         | 0.1.0 |
| **`values`**        | `Value[]` | Only available on Android.                                                                                                                                                    |         |       |

#### GetVersionResult

| Prop          | Type     | Description                                           | Since |
| ------------- | -------- | ----------------------------------------------------- | ----- |
| **`version`** | `string` | The version of the SQLite library used by the plugin. | 0.1.0 |

#### InitializeOptions

| Prop         | Type     | Description                                                                                                                                                                                                                                                                                                                                        | Default  | Since |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| **`worker`** | `Worker` | The Worker to use for the SQLite WebAssembly initialization. If provided, this worker will be passed to the sqlite3Worker1Promiser method for initializing the SQLite WebAssembly module in the web implementation. Only available on Web.                                                                                                         |          | 0.1.3 |
| **`vfs`**    | `Vfs`    | The VFS (virtual file system) that stores the databases. `opfs-sahpool` requires no COOP/COEP headers but only works in a single tab. The provided `worker` must install the pool by calling `sqlite3.installOpfsSAHPoolVfs()` before `sqlite3.initWorker1API()`. Databases stored by one VFS are not visible to the other. Only available on Web. | `'opfs'` | 0.4.1 |

#### OpenResult

| Prop             | Type     | Description                                  | Since |
| ---------------- | -------- | -------------------------------------------- | ----- |
| **`databaseId`** | `string` | A unique identifier for the opened database. | 0.1.0 |

#### OpenOptions

| Prop                    | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Default | Since |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- |
| **`encryptionKey`**     | `string`             | The encryption key to use for the database. If provided, the database will be opened as an encrypted database using the specified key. If not provided, the database will be opened as an unencrypted database. **Attention:** It's recommended to use a strong encryption key to protect sensitive data. This key should be kept secret and not hard-coded in your application. If you lose the encryption key, you will not be able to access the data in the database. **Tip:** Use the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin to securely store the encryption key. Only available on Android and iOS.                                                                                                                                                                                                                       |         | 0.1.0 |
| **`readOnly`**          | `boolean`            | Whether the database should be opened in read-only mode. Upgrade statements cannot be applied to a read-only database, so `open(...)` is rejected if the stored `user_version` is lower than `version`. Only available on Android and iOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false` | 0.1.0 |
| **`path`**              | `string`             | The path to the database file. If no file exists at the specified path, a new file will be created. If no path or URL is provided, the plugin will create a new in-memory database. On **Android**, the path can either be a simple filename or a file URI. If a simple filename is provided, the plugin will create the database in the default database directory (see [getDatabasePath](<https://developer.android.com/reference/android/content/Context#getDatabasePath(java.lang.String)>)). On **iOS**, the path can either be a simple filename or a file URL. If a simple filename is provided, the plugin will create the database in the default documents directory (see [documentsDirectory](https://developer.apple.com/documentation/foundation/url/documentsdirectory)). On **Web**, the path should be a simple filename without a directory (e.g., `mydb.sqlite3`). |         | 0.1.0 |
| **`androidExtensions`** | `AndroidExtension[]` | App-bundled SQLite extensions to load when opening the database. Only available on Android when the requery SQLite backend is bundled (see `capawesomeCapacitorSqliteIncludeRequery`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |         | 0.3.9 |
| **`upgradeStatements`** | `UpgradeStatement[]` | An array of upgrade statements to apply when opening the database. Each statement should specify the version of the database schema it applies to and the SQL statements to execute for the upgrade. The current version of the database schema can be checked using the `PRAGMA user_version;` command. The statements of all versions greater than the current `user_version` and up to `version` are executed in a single transaction together with the update of `user_version`. If a statement fails, the transaction is rolled back and the call is rejected.                                                                                                                                                                                                                                                                                                                  |         | 0.1.0 |
| **`version`**           | `number`             | The version of the database schema. If provided, the plugin will check the schema version and apply migrations if necessary. If not provided, the latest version of the upgrade statements will be used, if any. If neither `version` nor `upgradeStatements` are provided, the database version will not be managed by the plugin. The stored `user_version` is never lowered: if it is already equal to or higher than `version`, no upgrade statements are executed and the database is left untouched. **Attention:** The version must be an integer between 1 and 2147483647. The call is rejected otherwise.                                                                                                                                                                                                                                                                   |         | 0.1.0 |

#### AndroidExtension

| Prop             | Type     | Description                                                                                                                                                                                                                                     | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`name`**       | `string` | The bundled extension library name without the `lib` prefix or `.so` suffix. The plugin resolves the name to the corresponding native library bundled with the app. For example, `sqlite_tokenizer_ar` resolves to `libsqlite_tokenizer_ar.so`. | 0.3.9 |
| **`entryPoint`** | `string` | The extension entry point. If not provided, SQLite derives the entry point from the library name.                                                                                                                                               | 0.3.9 |

#### UpgradeStatement

| Prop             | Type       | Description                                                                                                                            | Since |
| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`version`**    | `number`   | The version of the database schema that this statement applies to.                                                                     | 0.1.0 |
| **`statements`** | `string[]` | The SQL statement to execute for the upgrade. This can be any valid SQL statement, such as `ALTER TABLE`, `CREATE TABLE`, or `INSERT`. | 0.1.0 |

#### QueryResult

| Prop          | Type        | Description                                                                                                                                                   | Default | Since |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`columns`** | `string[]`  | The column names in the result set.                                                                                                                           | `[]`    | 0.1.0 |
| **`rows`**    | `Value[][]` | The rows returned by the query. Each row is represented as an object where the keys are column names and the values are the corresponding values in that row. | `[]`    | 0.1.0 |

#### QueryOptions

| Prop             | Type      | Description                                                                                                    | Default | Since |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`databaseId`** | `string`  | The unique identifier for the database to query.                                                               |         | 0.1.0 |
| **`statement`**  | `string`  | The SQL statement to execute for the query. This should be a `SELECT` statement.                               |         | 0.1.0 |
| **`values`**     | `Value[]` | An array of values to bind to the SQL statement. Each value corresponds to a placeholder in the SQL statement. | `[]`    | 0.1.0 |

#### RollbackTransactionOptions

| Prop             | Type     | Description                                                          | Since |
| ---------------- | -------- | -------------------------------------------------------------------- | ----- |
| **`databaseId`** | `string` | The unique identifier for the database to rollback a transaction on. | 0.1.0 |

#### VacuumOptions

| Prop             | Type     | Description                                                          | Since |
| ---------------- | -------- | -------------------------------------------------------------------- | ----- |
| **`databaseId`** | `string` | The unique identifier for the database to run the VACUUM command on. | 0.1.0 |

### Type Aliases

#### Value

Represents a value that can be used in SQL statements.

This can include strings, numbers, arrays of numbers (for BLOBs), or `null`.

**Attention:** On Web, arrays of numbers (BLOBs) are not supported.

`string | number | number[] | null`

#### Vfs

The VFS (virtual file system) that stores the databases on Web.

- `opfs`: Requires the page to be cross-origin isolated (COOP/COEP headers). Supports multiple tabs.
- `opfs-sahpool`: Requires no COOP/COEP headers. Supports only a single tab.

`'opfs' | 'opfs-sahpool'`

## Key-Value Store

This plugin includes a built-in key-value store (`SqliteKeyValueStore`) that provides a simple API for storing and retrieving key-value pairs without writing SQL. The database is automatically created and managed under the hood.

```
import { Sqlite, SqliteKeyValueStore } from '@capawesome-team/capacitor-sqlite';

const store = new SqliteKeyValueStore(Sqlite);

// Set a value
await store.set({ key: 'settings', value: JSON.stringify({ theme: 'dark', notifications: true }) });

// Get a value
const result = await store.get({ key: 'settings' });
if (result.value) {
  const settings = JSON.parse(result.value);
  console.log(settings.theme); // 'dark'
  console.log(settings.notifications); // true
}

// Remove a value
await store.remove({ key: 'settings' });

// Clear all values
await store.clear();

// Get all keys
const keysResult = await store.keys();
console.log(keysResult.keys); // ['settings', 'user', 'preferences', ...]
```

Perfect for storing small amounts of data such as user preferences, app settings, or session data without risking data loss due to web view data clearing.

## ORMs

### Drizzle

This plugin is compatible with [Drizzle ORM](https://orm.drizzle.team/) via the [`@capawesome/capacitor-sqlite-drizzle`](https://github.com/capawesome-team/capacitor-sqlite-drivers/tree/main/packages/drizzle) adapter.

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';
import { drizzle } from '@capawesome/capacitor-sqlite-drizzle';
import * as schema from './schema';

const { databaseId } = await Sqlite.open({ path: 'my.db' });
const db = drizzle(Sqlite, { databaseId, schema });

const users = await db.select().from(schema.users);
```

Check out the [How to use Drizzle with Capacitor SQLite](https://capawesome.io/blog/how-to-use-drizzle-orm-with-capacitor-and-sqlite/) blog post for a step-by-step guide on how to set up and use Drizzle ORM with this plugin.

### Kysely

This plugin is compatible with [Kysely](https://kysely.dev/) via the [`@capawesome/capacitor-sqlite-kysely`](https://github.com/capawesome-team/capacitor-sqlite-drivers/tree/main/packages/kysely) dialect.

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';
import { Kysely } from 'kysely';
import { CapacitorSqliteDialect } from '@capawesome/capacitor-sqlite-kysely';

const { databaseId } = await Sqlite.open({ path: 'my.db' });
const db = new Kysely<Database>({
  dialect: new CapacitorSqliteDialect(Sqlite, { databaseId }),
});

const users = await db.selectFrom('users').selectAll().execute();
```

Check out the [How to use Kysely with Capacitor SQLite](https://capawesome.io/blog/how-to-use-kysely-with-capacitor-and-sqlite/) blog post for a step-by-step guide on how to set up and use Kysely with this plugin.

### TypeORM

This plugin is compatible with [TypeORM](https://typeorm.io/), a popular ORM for TypeScript and JavaScript.

```
import { Sqlite, SQLiteConnection } from '@capawesome-team/capacitor-sqlite';
import { DataSource, DataSourceOptions } from 'typeorm';

const createDataSource = async () => {
  return new DataSource({
    database: 'db',
    driver: new SQLiteConnection(Sqlite),
    entities: [
      // Your TypeORM entities here
    ],
    migrationsRun: false, // Required with capacitor type
    type: 'capacitor'
  });
};
```

Check out the [How to use TypeORM with Capacitor SQLite](https://capawesome.io/blog/how-to-use-typeorm-with-capacitor-and-sqlite/) blog post for a step-by-step guide on how to set up and use TypeORM with this plugin.

## Error Handling

Every method rejects with an `Error` whose `message` describes what went wrong. Errors that originate from SQLite additionally expose the primary [SQLite result code](https://www.sqlite.org/rescode.html) as a number in the `data.sqliteCode` property. This lets you handle specific failures programmatically instead of parsing the error message.

Only available on Android and iOS.

```
try {
  await Sqlite.open({ path: '/invalid/path/to.db' });
} catch (error) {
  if (error.data?.sqliteCode === 14) {
    // SQLITE_CANTOPEN: unable to open the database file
  }
}
```

## Limitations

This plugin has some limitations on certain platforms.

### Android

The Android implementation of this plugin has the following limitations:

- **Single statement per call**: Only one SQL statement can be executed per `execute(...)` or `query(...)` call. Statements joined by `;` will not all be executed. To run multiple statements, call `execute(...)` or `query(...)` once per statement.
- **Statements that return data must use `query(...)`**: `execute(...)` cannot run statements that return rows. For example, `PRAGMA journal_mode = WAL` and `PRAGMA journal_size_limit = ...` both return the resulting value and must be run via `query(...)`. `PRAGMA synchronous = ...` does not return a value and can be run via `execute(...)`.

### Web

The web implementation of this plugin has the following limitations:

- **BLOBs**: Arrays of numbers (BLOBs) are not supported. You can only use strings, numbers, and `null` as values in SQL statements.

### Electron

The Electron implementation of this plugin has the following limitations:

- **Encryption**: Database encryption is not supported.
- **Node.js version**: Requires Node.js 22.5.0 or later (Electron 33+) to use the native `node:sqlite` module.
- **Single statement per call**: Only one SQL statement can be executed per `execute(...)` or `query(...)` call. Statements joined by `;` will not all be executed. To run multiple statements, call `execute(...)` or `query(...)` once per statement.

## Troubleshooting

##### `SQLITE_ERROR: sqlite3 result code 1: no such vfs: opfs`

This error occurs when OPFS (Origin Private File System) cannot be instantiated. This is likely due to the server not sending the required headers for the web worker to be able to access the OPFS. To fix this, you need to add the following headers to your server configuration:

```
'Cross-Origin-Embedder-Policy': 'require-corp'
'Cross-Origin-Opener-Policy': 'same-origin'
```

Alternatively, use the `opfs-sahpool` VFS, which requires no headers (see [Can I use the plugin on the web without the COOP/COEP headers?](#can-i-use-the-plugin-on-the-web-without-the-coopcoep-headers)).

##### `SQLITE_ERROR: sqlite3 result code 1: no such vfs: opfs-sahpool`

This error occurs when `initialize()` was called with `vfs: 'opfs-sahpool'` but the pool is not available in the worker. Either the worker does not call `installOpfsSAHPoolVfs()` before `initWorker1API()`, or another tab of your app already holds the pool (see [Can I use the plugin on the web without the COOP/COEP headers?](#can-i-use-the-plugin-on-the-web-without-the-coopcoep-headers)).

##### `Sqlite.open()` never resolves in production

If `open()` hangs or never resolves while working in dev mode, this is typically caused by missing COOP/COEP headers in your production deployment. You need to configure your production web server (Netlify, Vercel, Nginx, Apache, etc.) to send these headers:

```
'Cross-Origin-Embedder-Policy': 'require-corp'
'Cross-Origin-Opener-Policy': 'same-origin'
```

To verify this is the issue, open Chrome DevTools → Network tab and check if these headers are present in the response for your HTML document.

##### `No such module 'SQLite'`

This error occurs when the `SQLite` module is not found in your iOS project. To fix this, make sure you have added the `CapawesomeTeamCapacitorSqlite/Plain` or `CapawesomeTeamCapacitorSqlite/SQLCipher` pod to your `Podfile` as described in the [Installation](#ios) section:

```
def capacitor_pods
  pod 'CapawesomeTeamCapacitorSqlite', :path => '../../node_modules/@capawesome-team/capacitor-sqlite'
end

target 'App' do
  capacitor_pods
  # Add your Pods here
+  pod 'CapawesomeTeamCapacitorSqlite/Plain', :path => '../../node_modules/@capawesome-team/capacitor-sqlite'
end
```

**Attention**: Both `CapawesomeTeamCapacitorSqlite` and `CapawesomeTeamCapacitorSqlite/Plain` or `CapawesomeTeamCapacitorSqlite/SQLCipher` must be included in the `Podfile`. The first one is required for the plugin to work, while the second one is required for the specific implementation (Plain or SQLCipher).

## FAQ

### When should I use SQLite instead of Vault or Secure Preferences?

All three plugins protect data on the device, but they target different problems:

- **SQLite** (this plugin) is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets — for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database.
- **[Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/)** is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background — typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information.
- **[Vault](https://capawesome.io/docs/sdks/capacitor/vault/)** is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action — a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an "app lock" screen.

A quick decision tree:

- Need queries, relations, or large datasets? → **SQLite**.
- Need encrypted key/value storage the app can read freely in the background? → **Secure Preferences**.
- Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? → **Vault**.

The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else.

### Is this plugin an alternative to Ionic Secure Storage?

Yes. [Ionic Secure Storage](https://ionic.io/products/secure-storage), which sunsets on December 31, 2027, provides an encrypted SQLite database based on SQLCipher — and so does this plugin: it offers 256 bit AES encryption via SQLCipher on Android and iOS (see the [Encryption](#encryption) section). Since both are built on SQLCipher and this plugin applies SQLCipher's default configuration, an existing database created by Ionic Secure Storage can generally be opened with the same encryption key — but verify this with your own database before migrating. For a step-by-step guide, check out the blog post [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/). If you only store key/value data, the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugin may be the better fit.

### Is this plugin an alternative to the Capacitor Community SQLite plugin?

Yes. Check out the blog post [Alternative to the Capacitor Community SQLite plugin](https://capawesome.io/blog/alternative-to-capacitor-community-sqlite-plugin/) for a detailed comparison of `@capacitor-community/sqlite` and this plugin, including a migration guide.

### Is database encryption supported on all platforms?

No, encryption is only available on Android and iOS, where the plugin provides 256 bit AES encryption via SQLCipher. On both platforms, SQLCipher is opt-in and requires additional setup, as described in the [Installation](#installation) section. On Electron, database encryption is not supported.

### Why does a changed SPM package trait have no effect?

After changing the package traits in your Capacitor configuration, run `npx cap sync ios`, let Xcode re-resolve the packages (File → Packages → Resolve Package Versions, or Reset Package Caches) and clean the build folder (Product → Clean Build Folder) before building again. You can check which SQLite version is active with `getVersion()`.

### Can I execute multiple SQL statements in a single call?

On Android and Electron, only one SQL statement can be executed per `execute(...)` or `query(...)` call. Statements joined by `;` will not all be executed. To run multiple statements, call `execute(...)` or `query(...)` once per statement, optionally wrapped in a transaction.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. It also works with popular ORMs like Drizzle, Kysely and TypeORM, as described in the [ORMs](#orms) section.

### Can I use the plugin on the web without the COOP/COEP headers?

Yes. By default, the plugin stores databases in the `opfs` VFS, which requires the page to be [cross-origin isolated](https://developer.mozilla.org/en-US/docs/Web/API/Window/crossOriginIsolated) via the COOP/COEP headers shown in the [Installation](#web) section. If your server cannot send these headers, or sends `Cross-Origin-Embedder-Policy: credentialless`, which WebKit does not implement, you can use the [OPFS SyncAccessHandle Pool VFS](https://sqlite.org/wasm/doc/trunk/persistence.md#vfs-opfs-sahpool) instead. It requires no headers and is the fastest OPFS option, but it has the following trade-offs:

- **Single tab**: The pool holds its files exclusively. Only one tab (or window) of your app can use the database at a time. Installing the pool in a second tab fails and `open()` rejects with `no such vfs: opfs-sahpool`.
- **Separate storage**: Databases stored by the `opfs` VFS are not visible to the pool and vice versa. Switching the VFS does not migrate existing data.
- **Back/forward cache**: A document restored from the back/forward cache no longer has a working pool. Terminate the worker on `pagehide` and reload the page on `pageshow` (see below).

Create a worker file that is served as a static asset (for example, `src/assets/sqlite3-worker1-sahpool.mjs`) and installs the pool before initializing the Worker API:

```
import sqlite3InitModule from '/assets/sqlite-wasm/index.mjs';

const sqlite3 = await sqlite3InitModule();
await sqlite3.installOpfsSAHPoolVfs();
sqlite3.initWorker1API();
```

The pool has a default capacity of six files and each database needs at least two of them (database and journal file). Pass `initialCapacity` to `installOpfsSAHPoolVfs()` if you need more. With Vite, import `@sqlite.org/sqlite-wasm` in the worker instead and create it with `new Worker(new URL('./sqlite3-worker1-sahpool.mjs', import.meta.url), { type: 'module' })`.

Then pass the worker and the VFS to `initialize()`:

```
import { Capacitor } from '@capacitor/core';
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const initialize = async () => {
  const isWeb = Capacitor.getPlatform() === 'web';
  if (isWeb) {
    const worker = new Worker('/assets/sqlite3-worker1-sahpool.mjs', { type: 'module' });
    // Release the pool when the page is unloaded or enters the back/forward cache
    window.addEventListener('pagehide', () => worker.terminate());
    window.addEventListener('pageshow', (event) => {
      if (event.persisted) {
        window.location.reload();
      }
    });
    await Sqlite.initialize({ worker, vfs: 'opfs-sahpool' });
  }
};
```

## Related Plugins

- [libSQL](https://capawesome.io/docs/sdks/capacitor/libsql/): Access libSQL databases.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.
- [Vault](https://capawesome.io/docs/sdks/capacitor/vault/): Securely store key/value pairs in lockable, biometric-protected vaults.

## Next steps

Here are a few resources to help you continue:

- Read [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/) if you are migrating from Ionic Secure Storage.
- Read [Alternative to the Capacitor Community SQLite plugin](https://capawesome.io/blog/alternative-to-capacitor-community-sqlite-plugin/) to see how this plugin compares.
- Store small pieces of sensitive data like tokens with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/).

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sqlite/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sqlite/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sqlite/LICENSE).

## Third-Party Notices

If you enable SQLCipher (see the [Encryption](#encryption) section), your application takes on the SQLCipher Community Edition BSD-style license obligations. You must reproduce the copyright notice and license text in a **user-accessible location** — typically an "About" or "Licensing" screen, or product documentation linked from the application. This plugin does not include a SQLCipher commercial license; the BSD attribution applies. See the [SQLCipher license](https://www.zetetic.net/sqlcipher/license/) for the full text.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Hipp, Wyrick & Company, Inc., Zetetic, LLC, or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `SQLite` is a registered trademark of Hipp, Wyrick & Company, Inc. [↩](#fnref:2 "Jump back to footnote 2 in the text")
1. `SQLCipher` is a registered trademark of Zetetic, LLC. [↩](#fnref:3 "Jump back to footnote 3 in the text")

# Capacitor Square Mobile Payments Plugin

Unofficial Capacitor plugin for [Square Mobile Payments SDK](https://developer.squareup.com/docs/mobile-payments-sdk).[1](#fn:1)

## Features

This plugin provides a comprehensive integration with Square's Mobile Payments SDK for in-person payment processing. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 💳 **Payment Processing**: Accept in-person payments with Square card readers.
- 📱 **Reader Management**: Pair, manage, and monitor Square card readers.
- 🔐 **Secure Authorization**: OAuth-based authorization with Square access tokens.
- 🎨 **Flexible UI**: Choose between Square's default payment UI or build your own custom interface.
- 📊 **Real-time Updates**: Listen to reader status changes, pairing events, and payment completion.
- 💰 **Multiple Payment Methods**: Support for contactless (tap), chip (dip), swipe, and manual entry.
- 🌐 **Online & Offline**: Process payments online or offline with automatic sync.
- 🧾 **Receipt Data**: Access card details, authorization codes, and EMV data for compliant receipts.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Square Mobile Payments plugin is typically used to accept in-person payments in a Capacitor app, for example:

- **Point of sale**: Turn your app into a POS system that accepts tap, dip, swipe, and manually entered card payments with Square card readers.
- **Tap to Pay on iPhone**: Accept contactless payments directly on an iPhone without additional hardware by linking a Square seller account with an Apple ID.
- **Mobile and pop-up sales**: Pair, monitor, and manage Square readers for markets, food trucks, or events, and process payments offline with automatic sync when connectivity is limited.
- **Compliant receipts**: Access card details, authorization codes, and EMV data of completed payments to generate compliant receipts.
- **Testing without hardware**: Use the mock reader in debug builds to test the whole payment flow without a physical reader.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-square-mobile-payments` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-square-mobile-payments
npx cap sync
```

### Android

#### SDK Initialization

The Square Mobile Payments SDK must be initialized in your `Application` class before using the plugin. Create a custom `Application` class (if you don't already have one) and add the following code:

1. Create a file `MainApplication.java` in your app's `android/app/src/main/java/<your-package>/` directory:

```
package com.example.app;

import android.app.Application;
import com.squareup.sdk.mobilepayments.MobilePaymentsSdk;

public class MainApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        MobilePaymentsSdk.initialize("YOUR_SQUARE_APPLICATION_ID", this);
    }
}
```

**Note**: Replace `YOUR_SQUARE_APPLICATION_ID` with your actual Square Application ID.

1. Register the custom `Application` class in your `AndroidManifest.xml`:

```
<application
    android:name=".MainApplication"
    ...>
```

#### 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:

- `$squareMobilePaymentsSdkVersion` version of `com.squareup.sdk:mobile-payments-sdk` (default: `2.3.4`)

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

### iOS

#### SDK Initialization

The Square Mobile Payments SDK must be initialized in your `AppDelegate.swift` file before using the plugin. Add the following code to your `AppDelegate.swift`:

1. Import the `SquareMobilePaymentsSDK` at the top of the file:

```
import SquareMobilePaymentsSDK
```

1. Add the Square Application ID to your `Info.plist` file:

```
<key>SquareApplicationID</key>
<string>YOUR_SQUARE_APPLICATION_ID_HERE</string>
```

**Note**: Replace `YOUR_SQUARE_APPLICATION_ID_HERE` with your actual Square Application ID. Do not use the placeholder value in production.

1. Initialize the SDK in the `application(_:didFinishLaunchingWithOptions:)` method:

```
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Initialize Square Mobile Payments SDK
    // Get the Square Application ID from info.plist
    if let squareAppID = Bundle.main.object(forInfoDictionaryKey: "SquareApplicationID") as? String,
       !squareAppID.isEmpty && squareAppID != "YOUR_SQUARE_APPLICATION_ID_HERE" {
        MobilePaymentsSDK.initialize(
            applicationLaunchOptions: launchOptions,
            squareApplicationID: squareAppID
        )
    }

    // Override point for customization after application launch.
    return true
}
```

#### Build Phases

Add a new "Run Script Phase" in Xcode to run the Square SDK setup script by following these steps:

1. On the **Build Phases** tab for your application target in Xcode, choose the + button (at the top left of the pane).
1. Choose **New Run Script Phase**. The new run script phase should be the last build phase.
1. Expand the new Run Script phase and enter the following script:

```
FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}"
"${FRAMEWORKS}/SquareMobilePaymentsSDK.framework/setup"
```

More details can be found in the [Square Mobile Payments SDK iOS setup guide](https://developer.squareup.com/docs/mobile-payments-sdk/ios).

#### Privacy Descriptions

Add the `NSLocationWhenInUseUsageDescription`, `NSBluetoothAlwaysUsageDescription`, and `NSMicrophoneUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why your app is requesting location, Bluetooth, and microphone permissions:

```
<key>NSBluetoothAlwaysUsageDescription</key>
<string>We need Bluetooth access to connect to Square card readers.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to confirm payments are occurring in a supported Square location.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need microphone access to receive data from magstripe card readers.</string>
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize and authorize the SDK, pair and list readers, start a payment, read the available card input methods, and listen for payment and reader events.

### Initialize and authorize the SDK

Initialize the SDK with your Square location ID and authorize it with a Square access token. The `initialize(...)` method must be called before any other method:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const initializeSDK = async () => {
  await SquareMobilePayments.initialize({
    locationId: 'YOUR_LOCATION_ID',
  });

  await SquareMobilePayments.authorize({
    accessToken: 'YOUR_ACCESS_TOKEN',
  });
};
```

### Check the authorization state

Check whether the SDK is currently authorized, for example on app start:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const checkAuthorization = async () => {
  const { authorized } = await SquareMobilePayments.isAuthorized();
  console.log('Authorized:', authorized);
};
```

### Pair a Square reader

Start the pairing process. The SDK searches for nearby readers and pairs with the first one found:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const pairReader = async () => {
  await SquareMobilePayments.startPairing();
};
```

### List the paired readers

Get all paired readers with their serial number, model, and status:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const getReaders = async () => {
  const { readers } = await SquareMobilePayments.getReaders();
  for (const reader of readers) {
    console.log('Reader:', reader.serialNumber, reader.model, reader.status);
  }
};
```

### Start a payment

Present the payment UI and process a payment with the specified parameters. Only one payment can be active at a time:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const processPayment = async () => {
  await SquareMobilePayments.startPayment({
    paymentParameters: {
      amountMoney: {
        amount: 100,
        currency: 'USD',
      },
      paymentAttemptId: crypto.randomUUID(),
    },
    promptParameters: {
      mode: 'DEFAULT',
      additionalMethods: ['KEYED'],
    },
  });
};
```

### Listen for payment events

Listen for successful, failed, and cancelled payments to react to the result of a payment flow:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const listenToPaymentEvents = () => {
  SquareMobilePayments.addListener('paymentDidFinish', (event) => {
    console.log('Payment completed:', event.payment.id);
    console.log('Amount:', event.payment.amountMoney.amount);
    console.log('Card:', event.payment.cardDetails?.card.lastFourDigits);
  });

  SquareMobilePayments.addListener('paymentDidFail', (event) => {
    console.error('Payment failed:', event.message);
  });

  SquareMobilePayments.addListener('paymentDidCancel', (event) => {
    console.log('Payment cancelled');
  });
};
```

### Listen for reader events

Listen for reader status changes and changes to the available card input methods:

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const listenToReaderEvents = () => {
  SquareMobilePayments.addListener('readerWasAdded', (event) => {
    console.log('Reader added:', event.reader.serialNumber);
  });

  SquareMobilePayments.addListener('readerDidChange', (event) => {
    console.log('Reader changed:', event.reader.serialNumber, event.change);
  });

  SquareMobilePayments.addListener('availableCardInputMethodsDidChange', (event) => {
    console.log('Available methods:', event.cardInputMethods);
  });
};
```

### Get the available card input methods

Read the card entry methods that are currently available based on the connected readers (e.g. tap, dip, swipe, or keyed entry):

```
import { SquareMobilePayments } from '@capawesome/capacitor-square-mobile-payments';

const getAvailableMethods = async () => {
  const { cardInputMethods } = await SquareMobilePayments.getAvailableCardInputMethods();
  console.log('Available card input methods:', cardInputMethods);
};
```

## API

- [`initialize(...)`](#initialize)
- [`authorize(...)`](#authorize)
- [`isAuthorized()`](#isauthorized)
- [`deauthorize()`](#deauthorize)
- [`showSettings()`](#showsettings)
- [`showMockReader()`](#showmockreader)
- [`hideMockReader()`](#hidemockreader)
- [`getSettings()`](#getsettings)
- [`startPairing()`](#startpairing)
- [`stopPairing()`](#stoppairing)
- [`isPairingInProgress()`](#ispairinginprogress)
- [`getReaders()`](#getreaders)
- [`forgetReader(...)`](#forgetreader)
- [`retryConnection(...)`](#retryconnection)
- [`startPayment(...)`](#startpayment)
- [`cancelPayment()`](#cancelpayment)
- [`getAvailableCardInputMethods()`](#getavailablecardinputmethods)
- [`linkAppleAccount()`](#linkappleaccount)
- [`relinkAppleAccount()`](#relinkappleaccount)
- [`isAppleAccountLinked()`](#isappleaccountlinked)
- [`isDeviceCapable()`](#isdevicecapable)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('readerPairingDidBegin', ...)`](#addlistenerreaderpairingdidbegin-)
- [`addListener('readerPairingDidSucceed', ...)`](#addlistenerreaderpairingdidsucceed-)
- [`addListener('readerPairingDidFail', ...)`](#addlistenerreaderpairingdidfail-)
- [`addListener('readerWasAdded', ...)`](#addlistenerreaderwasadded-)
- [`addListener('readerWasRemoved', ...)`](#addlistenerreaderwasremoved-)
- [`addListener('readerDidChange', ...)`](#addlistenerreaderdidchange-)
- [`addListener('availableCardInputMethodsDidChange', ...)`](#addlisteneravailablecardinputmethodsdidchange-)
- [`addListener('paymentDidFinish', ...)`](#addlistenerpaymentdidfinish-)
- [`addListener('paymentDidFail', ...)`](#addlistenerpaymentdidfail-)
- [`addListener('paymentDidCancel', ...)`](#addlistenerpaymentdidcancel-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the Square Mobile Payments SDK.

This method must be called before any other method.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### authorize(...)

```
authorize(options: AuthorizeOptions) => Promise<void>
```

Authorize the SDK with a Square access token.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AuthorizeOptions` |

**Since:** 0.0.1

______________________________________________________________________

### isAuthorized()

```
isAuthorized() => Promise<IsAuthorizedResult>
```

Check if the SDK is currently authorized.

Only available on Android and iOS.

**Returns:** `Promise<IsAuthorizedResult>`

**Since:** 0.0.1

______________________________________________________________________

### deauthorize()

```
deauthorize() => Promise<void>
```

Deauthorize the SDK and clear the current authorization.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### showSettings()

```
showSettings() => Promise<void>
```

Show the Square settings screen.

This displays a pre-built settings UI where merchants can view and manage their paired readers.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### showMockReader()

```
showMockReader() => Promise<void>
```

Show the Mock Reader UI for testing.

This displays a mock reader interface for testing payment flows without physical hardware. This is only for development and testing purposes and is therefore only available in debug builds.

Only available on Android and iOS.

**Since:** 0.1.1

______________________________________________________________________

### hideMockReader()

```
hideMockReader() => Promise<void>
```

Hide the Mock Reader UI.

Only available on Android and iOS.

**Since:** 0.1.1

______________________________________________________________________

### getSettings()

```
getSettings() => Promise<GetSettingsResult>
```

Get the current SDK settings.

Only available on Android and iOS.

**Returns:** `Promise<GetSettingsResult>`

**Since:** 0.0.1

______________________________________________________________________

### startPairing()

```
startPairing() => Promise<void>
```

Start pairing with a Square reader.

This initiates the reader pairing process. The SDK will search for nearby readers and pair with the first one found.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### stopPairing()

```
stopPairing() => Promise<void>
```

Stop the reader pairing process.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### isPairingInProgress()

```
isPairingInProgress() => Promise<IsPairingInProgressResult>
```

Check if a pairing process is currently in progress.

Only available on Android and iOS.

**Returns:** `Promise<IsPairingInProgressResult>`

**Since:** 0.0.1

______________________________________________________________________

### getReaders()

```
getReaders() => Promise<GetReadersResult>
```

Get a list of all paired readers.

Only available on Android and iOS.

**Returns:** `Promise<GetReadersResult>`

**Since:** 0.0.1

______________________________________________________________________

### forgetReader(...)

```
forgetReader(options: ForgetReaderOptions) => Promise<void>
```

Forget a paired reader.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ForgetReaderOptions` |

**Since:** 0.0.1

______________________________________________________________________

### retryConnection(...)

```
retryConnection(options: RetryConnectionOptions) => Promise<void>
```

Retry connecting to a reader.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `RetryConnectionOptions` |

**Since:** 0.0.1

______________________________________________________________________

### startPayment(...)

```
startPayment(options: StartPaymentOptions) => Promise<void>
```

Start a payment flow.

This presents the payment UI and processes the payment using the specified parameters. Only one payment can be active at a time.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `StartPaymentOptions` |

**Since:** 0.0.1

______________________________________________________________________

### cancelPayment()

```
cancelPayment() => Promise<void>
```

Cancel an ongoing payment.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### getAvailableCardInputMethods()

```
getAvailableCardInputMethods() => Promise<GetAvailableCardInputMethodsResult>
```

Get the currently available card input methods.

This returns the card entry methods that are available based on the connected readers (e.g., TAP, DIP, SWIPE, KEYED).

Only available on Android and iOS.

**Returns:** `Promise<GetAvailableCardInputMethodsResult>`

**Since:** 0.0.1

______________________________________________________________________

### linkAppleAccount()

```
linkAppleAccount() => Promise<void>
```

Link a Square seller account with an Apple ID for Tap to Pay on iPhone.

Presents an Apple sheet prompting the user to accept the Tap to Pay on iPhone terms and conditions.

Only available on iOS.

**Since:** 0.1.3

______________________________________________________________________

### relinkAppleAccount()

```
relinkAppleAccount() => Promise<void>
```

Re-link a Square seller account with a different Apple ID.

Presents an Apple sheet to change the associated Apple ID by showing the Tap to Pay terms and conditions again.

Only available on iOS.

**Since:** 0.1.3

______________________________________________________________________

### isAppleAccountLinked()

```
isAppleAccountLinked() => Promise<IsAppleAccountLinkedResult>
```

Check if an Apple ID is already linked to a Square seller account.

Only available on iOS.

**Returns:** `Promise<IsAppleAccountLinkedResult>`

**Since:** 0.1.3

______________________________________________________________________

### isDeviceCapable()

```
isDeviceCapable() => Promise<IsDeviceCapableResult>
```

Check if the device is capable of Tap to Pay on iPhone.

Only available on iOS.

**Returns:** `Promise<IsDeviceCapableResult>`

**Since:** 0.1.3

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the current permission status.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the required permissions.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerPairingDidBegin', ...)

```
addListener(eventName: 'readerPairingDidBegin', listenerFunc: ReaderPairingDidBeginListener) => Promise<PluginListenerHandle>
```

Listen for reader pairing events.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'readerPairingDidBegin'`       |
| **`listenerFunc`** | `ReaderPairingDidBeginListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerPairingDidSucceed', ...)

```
addListener(eventName: 'readerPairingDidSucceed', listenerFunc: ReaderPairingDidSucceedListener) => Promise<PluginListenerHandle>
```

Listen for successful reader pairing events.

Only available on Android and iOS.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'readerPairingDidSucceed'`       |
| **`listenerFunc`** | `ReaderPairingDidSucceedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerPairingDidFail', ...)

```
addListener(eventName: 'readerPairingDidFail', listenerFunc: ReaderPairingDidFailListener) => Promise<PluginListenerHandle>
```

Listen for failed reader pairing events.

Only available on Android and iOS.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'readerPairingDidFail'`       |
| **`listenerFunc`** | `ReaderPairingDidFailListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerWasAdded', ...)

```
addListener(eventName: 'readerWasAdded', listenerFunc: ReaderWasAddedListener) => Promise<PluginListenerHandle>
```

Listen for reader added events.

Only available on Android and iOS.

| Param              | Type                     |
| ------------------ | ------------------------ |
| **`eventName`**    | `'readerWasAdded'`       |
| **`listenerFunc`** | `ReaderWasAddedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerWasRemoved', ...)

```
addListener(eventName: 'readerWasRemoved', listenerFunc: ReaderWasRemovedListener) => Promise<PluginListenerHandle>
```

Listen for reader removed events.

Only available on Android and iOS.

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | `'readerWasRemoved'`       |
| **`listenerFunc`** | `ReaderWasRemovedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('readerDidChange', ...)

```
addListener(eventName: 'readerDidChange', listenerFunc: ReaderDidChangeListener) => Promise<PluginListenerHandle>
```

Listen for reader status and property changes.

Only available on Android and iOS.

| Param              | Type                      |
| ------------------ | ------------------------- |
| **`eventName`**    | `'readerDidChange'`       |
| **`listenerFunc`** | `ReaderDidChangeListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('availableCardInputMethodsDidChange', ...)

```
addListener(eventName: 'availableCardInputMethodsDidChange', listenerFunc: AvailableCardInputMethodsDidChangeListener) => Promise<PluginListenerHandle>
```

Listen for available card input method changes.

Only available on Android and iOS.

| Param              | Type                                         |
| ------------------ | -------------------------------------------- |
| **`eventName`**    | `'availableCardInputMethodsDidChange'`       |
| **`listenerFunc`** | `AvailableCardInputMethodsDidChangeListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paymentDidFinish', ...)

```
addListener(eventName: 'paymentDidFinish', listenerFunc: PaymentDidFinishListener) => Promise<PluginListenerHandle>
```

Listen for successful payment completion events.

Only available on Android and iOS.

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | `'paymentDidFinish'`       |
| **`listenerFunc`** | `PaymentDidFinishListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paymentDidFail', ...)

```
addListener(eventName: 'paymentDidFail', listenerFunc: PaymentDidFailListener) => Promise<PluginListenerHandle>
```

Listen for failed payment events.

Only available on Android and iOS.

| Param              | Type                     |
| ------------------ | ------------------------ |
| **`eventName`**    | `'paymentDidFail'`       |
| **`listenerFunc`** | `PaymentDidFailListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paymentDidCancel', ...)

```
addListener(eventName: 'paymentDidCancel', listenerFunc: PaymentDidCancelListener) => Promise<PluginListenerHandle>
```

Listen for cancelled payment events.

Only available on Android and iOS.

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | `'paymentDidCancel'`       |
| **`listenerFunc`** | `PaymentDidCancelListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### InitializeOptions

| Prop             | Type     | Description             | Since |
| ---------------- | -------- | ----------------------- | ----- |
| **`locationId`** | `string` | The Square location ID. | 0.0.1 |

#### AuthorizeOptions

| Prop              | Type     | Description              | Since |
| ----------------- | -------- | ------------------------ | ----- |
| **`accessToken`** | `string` | The Square access token. | 0.0.1 |

#### IsAuthorizedResult

| Prop             | Type      | Description                              | Since |
| ---------------- | --------- | ---------------------------------------- | ----- |
| **`authorized`** | `boolean` | Whether the SDK is currently authorized. | 0.0.1 |

#### GetSettingsResult

| Prop              | Type          | Description              | Since |
| ----------------- | ------------- | ------------------------ | ----- |
| **`version`**     | `string`      | The SDK version.         | 0.0.1 |
| **`environment`** | `Environment` | The current environment. | 0.0.1 |

#### IsPairingInProgressResult

| Prop             | Type      | Description                                         | Since |
| ---------------- | --------- | --------------------------------------------------- | ----- |
| **`inProgress`** | `boolean` | Whether a pairing process is currently in progress. | 0.0.1 |

#### GetReadersResult

| Prop          | Type           | Description                 | Since |
| ------------- | -------------- | --------------------------- | ----- |
| **`readers`** | `ReaderInfo[]` | The list of paired readers. | 0.0.1 |

#### ReaderInfo

| Prop                            | Type                    | Description                                                                                                | Since |
| ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | ----- |
| **`serialNumber`**              | `string`                | The reader's serial number.                                                                                | 0.0.1 |
| **`model`**                     | `ReaderModel`           | The reader's model.                                                                                        | 0.0.1 |
| **`status`**                    | `ReaderStatus`          | The reader's current status.                                                                               | 0.0.1 |
| **`firmwareVersion`**           | `string`                | The reader's firmware version.                                                                             | 0.0.1 |
| **`batteryLevel`**              | `number`                | The reader's battery level (0-100).                                                                        | 0.0.1 |
| **`isCharging`**                | `boolean`               | Whether the reader is currently charging.                                                                  | 0.0.1 |
| **`supportedCardInputMethods`** | `CardInputMethod[]`     | The card input methods supported by this reader.                                                           | 0.0.1 |
| **`unavailableReasonInfo`**     | `UnavailableReasonInfo` | Additional information about why the reader is unavailable. Only present when status is ReaderUnavailable. | 0.0.1 |

#### UnavailableReasonInfo

| Prop          | Type                | Description                                                        | Since |
| ------------- | ------------------- | ------------------------------------------------------------------ | ----- |
| **`reason`**  | `UnavailableReason` | The reason code why the reader is unavailable.                     | 0.0.1 |
| **`message`** | `string`            | A human-readable message describing why the reader is unavailable. | 0.0.1 |

#### ForgetReaderOptions

| Prop               | Type     | Description                                | Since |
| ------------------ | -------- | ------------------------------------------ | ----- |
| **`serialNumber`** | `string` | The serial number of the reader to forget. | 0.0.1 |

#### RetryConnectionOptions

| Prop               | Type     | Description                                          | Since |
| ------------------ | -------- | ---------------------------------------------------- | ----- |
| **`serialNumber`** | `string` | The serial number of the reader to retry connection. | 0.0.1 |

#### StartPaymentOptions

| Prop                    | Type                | Description             | Since |
| ----------------------- | ------------------- | ----------------------- | ----- |
| **`paymentParameters`** | `PaymentParameters` | The payment parameters. | 0.0.1 |
| **`promptParameters`**  | `PromptParameters`  | The prompt parameters.  | 0.0.1 |

#### PaymentParameters

| Prop                   | Type             | Description                                                                                                                                                 | Default                     | Since |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----- |
| **`amountMoney`**      | `Money`          | The amount of money to charge.                                                                                                                              |                             | 0.0.1 |
| **`paymentAttemptId`** | `string`         | A unique identifier for this payment attempt. This is used for idempotent payment requests.                                                                 |                             | 0.0.1 |
| **`processingMode`**   | `ProcessingMode` | The processing mode for this payment.                                                                                                                       | `ProcessingMode.AutoDetect` | 0.0.1 |
| **`referenceId`**      | `string`         | A user-defined reference ID to associate with the payment.                                                                                                  |                             | 0.0.1 |
| **`note`**             | `string`         | An optional note to add to the payment.                                                                                                                     |                             | 0.0.1 |
| **`orderId`**          | `string`         | The Square order ID to associate with this payment.                                                                                                         |                             | 0.0.1 |
| **`tipMoney`**         | `Money`          | The tip amount.                                                                                                                                             |                             | 0.0.1 |
| **`applicationFee`**   | `Money`          | The application fee.                                                                                                                                        |                             | 0.0.1 |
| **`autocomplete`**     | `boolean`        | Whether to automatically complete the payment. If false, the payment will be authorized but not captured, requiring manual completion via the Payments API. | `true`                      | 0.0.1 |
| **`delayDuration`**    | `string`         | The duration to delay before automatically completing or canceling the payment. Only applicable when autocomplete is false.                                 |                             | 0.0.1 |
| **`delayAction`**      | `DelayAction`    | The action to take when the delay duration expires. Only applicable when autocomplete is false.                                                             |                             | 0.0.1 |

#### Money

| Prop           | Type           | Description                                                     | Since |
| -------------- | -------------- | --------------------------------------------------------------- | ----- |
| **`amount`**   | `number`       | The amount in the smallest currency unit (e.g., cents for USD). | 0.0.1 |
| **`currency`** | `CurrencyCode` | The ISO 4217 currency code.                                     | 0.0.1 |

#### PromptParameters

| Prop                    | Type                        | Description                          | Default              | Since |
| ----------------------- | --------------------------- | ------------------------------------ | -------------------- | ----- |
| **`mode`**              | `PromptMode`                | The prompt mode.                     | `PromptMode.Default` | 0.0.1 |
| **`additionalMethods`** | `AdditionalPaymentMethod[]` | Additional payment methods to allow. | `[]`                 | 0.0.1 |

#### GetAvailableCardInputMethodsResult

| Prop                   | Type                | Description                       | Since |
| ---------------------- | ------------------- | --------------------------------- | ----- |
| **`cardInputMethods`** | `CardInputMethod[]` | The available card input methods. | 0.0.1 |

#### IsAppleAccountLinkedResult

| Prop         | Type      | Description                                                 | Since |
| ------------ | --------- | ----------------------------------------------------------- | ----- |
| **`linked`** | `boolean` | Whether an Apple ID is linked to the Square seller account. | 0.1.3 |

#### IsDeviceCapableResult

| Prop          | Type      | Description                                            | Since |
| ------------- | --------- | ------------------------------------------------------ | ----- |
| **`capable`** | `boolean` | Whether the device is capable of Tap to Pay on iPhone. | 0.1.3 |

#### PermissionStatus

| Prop                   | Type              | Description                                                                                                                                 | Since |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`location`**         | `PermissionState` | Permission state for accessing location. Required to confirm that payments are occurring in a supported Square location.                    | 0.0.1 |
| **`recordAudio`**      | `PermissionState` | Permission state for recording audio. Required to receive data from magstripe readers.                                                      | 0.0.1 |
| **`bluetoothConnect`** | `PermissionState` | Permission state for Bluetooth connect. Required to receive data from contactless and chip readers. Only available on Android.              | 0.0.1 |
| **`bluetoothScan`**    | `PermissionState` | Permission state for Bluetooth scan. Required to store information during checkout. Only available on Android.                              | 0.0.1 |
| **`readPhoneState`**   | `PermissionState` | Permission state for reading phone state. Required to identify the device sending information to Square servers. Only available on Android. | 0.0.1 |
| **`bluetooth`**        | `PermissionState` | Permission state for using Bluetooth. Only available on iOS.                                                                                | 0.0.1 |

#### PluginListenerHandle

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

#### ReaderPairingDidFailEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`code`**    | `string` | The error code.    | 0.0.1 |
| **`message`** | `string` | The error message. | 0.0.1 |

#### ReaderWasAddedEvent

| Prop         | Type         | Description                | Since |
| ------------ | ------------ | -------------------------- | ----- |
| **`reader`** | `ReaderInfo` | The reader that was added. | 0.0.1 |

#### ReaderWasRemovedEvent

| Prop         | Type         | Description                  | Since |
| ------------ | ------------ | ---------------------------- | ----- |
| **`reader`** | `ReaderInfo` | The reader that was removed. | 0.0.1 |

#### ReaderDidChangeEvent

| Prop         | Type           | Description                       | Since |
| ------------ | -------------- | --------------------------------- | ----- |
| **`reader`** | `ReaderInfo`   | The reader that changed.          | 0.0.1 |
| **`change`** | `ReaderChange` | The type of change that occurred. | 0.0.1 |

#### AvailableCardInputMethodsDidChangeEvent

| Prop                   | Type                | Description                       | Since |
| ---------------------- | ------------------- | --------------------------------- | ----- |
| **`cardInputMethods`** | `CardInputMethod[]` | The available card input methods. | 0.0.1 |

#### PaymentDidFinishEvent

| Prop          | Type      | Description            | Since |
| ------------- | --------- | ---------------------- | ----- |
| **`payment`** | `Payment` | The completed payment. | 0.0.1 |

#### Payment

| Prop                 | Type                 | Description                                                    | Since                                                                                        |
| -------------------- | -------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **`id`**             | \`string             | null\`                                                         | The unique identifier for this payment. For offline payments, this may be null until synced. |
| **`type`**           | `PaymentType`        | The payment type.                                              | 0.0.1                                                                                        |
| **`status`**         | `PaymentStatus`      | The payment status.                                            | 0.0.1                                                                                        |
| **`amountMoney`**    | `Money`              | The amount paid.                                               | 0.0.1                                                                                        |
| **`tipMoney`**       | `Money`              | The tip amount.                                                | 0.0.1                                                                                        |
| **`applicationFee`** | `Money`              | The application fee.                                           | 0.0.1                                                                                        |
| **`referenceId`**    | `string`             | The reference ID provided in the payment parameters.           | 0.0.1                                                                                        |
| **`orderId`**        | `string`             | The order ID associated with this payment.                     | 0.0.1                                                                                        |
| **`cardDetails`**    | `CardPaymentDetails` | [Card](#card) payment details. Only present for card payments. | 0.0.1                                                                                        |
| **`createdAt`**      | `string`             | The time the payment was created (ISO 8601 format).            | 0.0.1                                                                                        |
| **`updatedAt`**      | `string`             | The time the payment was updated (ISO 8601 format).            | 0.0.1                                                                                        |

#### CardPaymentDetails

| Prop                    | Type              | Description                     | Since |
| ----------------------- | ----------------- | ------------------------------- | ----- |
| **`card`**              | `Card`            | The card information.           | 0.0.1 |
| **`entryMethod`**       | `CardInputMethod` | The card entry method used.     | 0.0.1 |
| **`authorizationCode`** | `string`          | The authorization code.         | 0.0.1 |
| **`applicationName`**   | `string`          | The EMV application name.       | 0.0.1 |
| **`applicationId`**     | `string`          | The EMV application identifier. | 0.0.1 |

#### Card

| Prop                  | Type        | Description                              | Since |
| --------------------- | ----------- | ---------------------------------------- | ----- |
| **`brand`**           | `CardBrand` | The card brand.                          | 0.0.1 |
| **`lastFourDigits`**  | `string`    | The last four digits of the card number. | 0.0.1 |
| **`cardholderName`**  | `string`    | The cardholder name.                     | 0.0.1 |
| **`expirationMonth`** | `number`    | The card expiration month (1-12).        | 0.0.1 |
| **`expirationYear`**  | `number`    | The card expiration year.                | 0.0.1 |

#### PaymentDidFailEvent

| Prop          | Type      | Description         | Since |
| ------------- | --------- | ------------------- | ----- |
| **`payment`** | `Payment` | The failed payment. | 0.0.1 |
| **`code`**    | `string`  | The error code.     | 0.0.1 |
| **`message`** | `string`  | The error message.  | 0.0.1 |

#### PaymentDidCancelEvent

| Prop          | Type      | Description            | Since |
| ------------- | --------- | ---------------------- | ----- |
| **`payment`** | `Payment` | The cancelled payment. | 0.0.1 |

### Type Aliases

#### CurrencyCode

`string`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### ReaderPairingDidBeginListener

Callback to receive reader pairing start notifications.

`(): void`

#### ReaderPairingDidSucceedListener

Callback to receive reader pairing success notifications.

`(): void`

#### ReaderPairingDidFailListener

Callback to receive reader pairing failure notifications.

`(event: ReaderPairingDidFailEvent): void`

#### ReaderWasAddedListener

Callback to receive reader added notifications.

`(event: ReaderWasAddedEvent): void`

#### ReaderWasRemovedListener

Callback to receive reader removed notifications.

`(event: ReaderWasRemovedEvent): void`

#### ReaderDidChangeListener

Callback to receive reader change notifications.

`(event: ReaderDidChangeEvent): void`

#### AvailableCardInputMethodsDidChangeListener

Callback to receive available card input method change notifications.

`(event: AvailableCardInputMethodsDidChangeEvent): void`

#### PaymentDidFinishListener

Callback to receive payment completion notifications.

`(event: PaymentDidFinishEvent): void`

#### PaymentDidFailListener

Callback to receive payment failure notifications.

`(event: PaymentDidFailEvent): void`

#### PaymentDidCancelListener

Callback to receive payment cancellation notifications.

`(event: PaymentDidCancelEvent): void`

### Enums

#### Environment

| Members          | Value          | Description                      | Since |
| ---------------- | -------------- | -------------------------------- | ----- |
| **`Production`** | `'production'` | Production environment.          | 0.0.1 |
| **`Sandbox`**    | `'sandbox'`    | Sandbox environment for testing. | 0.0.1 |

#### ReaderModel

| Members                  | Value                    | Description                             | Since |
| ------------------------ | ------------------------ | --------------------------------------- | ----- |
| **`ContactlessAndChip`** | `'CONTACTLESS_AND_CHIP'` | Square Reader for contactless and chip. | 0.0.1 |
| **`Magstripe`**          | `'MAGSTRIPE'`            | Square Reader for magstripe.            | 0.0.1 |
| **`Stand`**              | `'STAND'`                | Square Stand.                           | 0.0.1 |
| **`TapToPay`**           | `'TAP_TO_PAY'`           | Tap to Pay on iPhone.                   | 0.1.3 |
| **`Unknown`**            | `'UNKNOWN'`              | Unknown reader model.                   | 0.0.1 |

#### ReaderStatus

| Members                  | Value                    | Description                                                          | Since |
| ------------------------ | ------------------------ | -------------------------------------------------------------------- | ----- |
| **`Ready`**              | `'READY'`                | Reader is paired, connected, and ready to accept payments.           | 0.0.1 |
| **`ConnectingToSquare`** | `'CONNECTING_TO_SQUARE'` | Reader is connecting to Square servers.                              | 0.0.1 |
| **`ConnectingToDevice`** | `'CONNECTING_TO_DEVICE'` | Reader is connecting to the mobile device.                           | 0.0.1 |
| **`Faulty`**             | `'FAULTY'`               | Reader has a hardware or connection error in an unrecoverable state. | 0.0.1 |
| **`ReaderUnavailable`**  | `'READER_UNAVAILABLE'`   | Reader is connected but unable to process payments.                  | 0.0.1 |

#### CardInputMethod

| Members     | Value     | Description                 | Since |
| ----------- | --------- | --------------------------- | ----- |
| **`Tap`**   | `'TAP'`   | Contactless card tap (NFC). | 0.0.1 |
| **`Dip`**   | `'DIP'`   | EMV chip card insertion.    | 0.0.1 |
| **`Swipe`** | `'SWIPE'` | Magnetic stripe swipe.      | 0.0.1 |
| **`Keyed`** | `'KEYED'` | Manually keyed card entry.  | 0.0.1 |

#### UnavailableReason

| Members                        | Value                          | Description                                               | Since |
| ------------------------------ | ------------------------------ | --------------------------------------------------------- | ----- |
| **`BluetoothError`**           | `'BLUETOOTH_ERROR'`            | Bluetooth connection issue. Only available on iOS.        | 0.0.1 |
| **`BluetoothFailure`**         | `'BLUETOOTH_FAILURE'`          | Bluetooth failure. Only available on Android.             | 0.0.1 |
| **`BluetoothDisabled`**        | `'BLUETOOTH_DISABLED'`         | Bluetooth is disabled. Only available on Android.         | 0.0.1 |
| **`FirmwareUpdate`**           | `'FIRMWARE_UPDATE'`            | Reader firmware is updating. Only available on iOS.       | 0.0.1 |
| **`BlockingUpdate`**           | `'BLOCKING_UPDATE'`            | Blocking firmware update. Only available on Android.      | 0.0.1 |
| **`ReaderUnavailableOffline`** | `'READER_UNAVAILABLE_OFFLINE'` | Reader is unavailable offline. Only available on Android. | 0.0.1 |
| **`DeviceDeveloperMode`**      | `'DEVICE_DEVELOPER_MODE'`      | Device is in developer mode. Only available on Android.   | 0.0.1 |
| **`Unknown`**                  | `'UNKNOWN'`                    | Unknown reason.                                           | 0.0.1 |

#### ProcessingMode

| Members           | Value            | Description                                                        | Since |
| ----------------- | ---------------- | ------------------------------------------------------------------ | ----- |
| **`AutoDetect`**  | `'AUTO_DETECT'`  | Automatically detect the best processing mode (online or offline). | 0.0.1 |
| **`OnlineOnly`**  | `'ONLINE_ONLY'`  | Process the payment online only.                                   | 0.0.1 |
| **`OfflineOnly`** | `'OFFLINE_ONLY'` | Allow offline payment processing.                                  | 0.0.1 |

#### DelayAction

| Members        | Value        | Description                                                | Since |
| -------------- | ------------ | ---------------------------------------------------------- | ----- |
| **`Complete`** | `'COMPLETE'` | Automatically complete the payment when the delay expires. | 0.0.1 |
| **`Cancel`**   | `'CANCEL'`   | Automatically cancel the payment when the delay expires.   | 0.0.1 |

#### PromptMode

| Members       | Value       | Description                        | Since |
| ------------- | ----------- | ---------------------------------- | ----- |
| **`Default`** | `'DEFAULT'` | Use the default Square payment UI. | 0.0.1 |
| **`Custom`**  | `'CUSTOM'`  | Use a custom payment UI.           | 0.0.1 |

#### AdditionalPaymentMethod

| Members     | Value     | Description                      | Since |
| ----------- | --------- | -------------------------------- | ----- |
| **`Keyed`** | `'KEYED'` | Allow manually keyed card entry. | 0.0.1 |
| **`Cash`**  | `'CASH'`  | Allow cash payments.             | 0.0.1 |

#### ReaderChange

| Members                       | Value                          | Description                                                        | Since |
| ----------------------------- | ------------------------------ | ------------------------------------------------------------------ | ----- |
| **`BatteryDidBeginCharging`** | `'BATTERY_DID_BEGIN_CHARGING'` | Reader battery started charging. Only available on iOS.            | 0.0.1 |
| **`BatteryDidEndCharging`**   | `'BATTERY_DID_END_CHARGING'`   | Reader battery stopped charging. Only available on iOS.            | 0.0.1 |
| **`BatteryLevelDidChange`**   | `'BATTERY_LEVEL_DID_CHANGE'`   | Reader battery level changed. Only available on iOS.               | 0.0.1 |
| **`BatteryCharging`**         | `'BATTERY_CHARGING'`           | Reader battery charging status changed. Only available on Android. | 0.0.1 |
| **`Added`**                   | `'ADDED'`                      | Reader was added. Only available on Android.                       | 0.0.1 |
| **`Removed`**                 | `'REMOVED'`                    | Reader was removed. Only available on Android.                     | 0.0.1 |
| **`StatusDidChange`**         | `'STATUS_DID_CHANGE'`          | Reader status changed.                                             | 0.0.1 |

#### PaymentType

| Members       | Value       | Description                            | Since |
| ------------- | ----------- | -------------------------------------- | ----- |
| **`Online`**  | `'ONLINE'`  | [Payment](#payment) processed online.  | 0.0.1 |
| **`Offline`** | `'OFFLINE'` | [Payment](#payment) processed offline. | 0.0.1 |

#### PaymentStatus

| Members         | Value         | Description                                             | Since |
| --------------- | ------------- | ------------------------------------------------------- | ----- |
| **`Completed`** | `'COMPLETED'` | [Payment](#payment) was completed successfully.         | 0.0.1 |
| **`Approved`**  | `'APPROVED'`  | [Payment](#payment) was approved but not yet completed. | 0.0.1 |
| **`Canceled`**  | `'CANCELED'`  | [Payment](#payment) was canceled.                       | 0.0.1 |
| **`Failed`**    | `'FAILED'`    | [Payment](#payment) failed.                             | 0.0.1 |
| **`Pending`**   | `'PENDING'`   | [Payment](#payment) is pending.                         | 0.0.1 |

#### CardBrand

| Members               | Value                | Description                  | Since |
| --------------------- | -------------------- | ---------------------------- | ----- |
| **`Visa`**            | `'VISA'`             | Visa card.                   | 0.0.1 |
| **`Mastercard`**      | `'MASTERCARD'`       | Mastercard.                  | 0.0.1 |
| **`AmericanExpress`** | `'AMERICAN_EXPRESS'` | American Express card.       | 0.0.1 |
| **`Discover`**        | `'DISCOVER'`         | Discover card.               | 0.0.1 |
| **`DiscoverDiners`**  | `'DISCOVER_DINERS'`  | Discover Diners card.        | 0.0.1 |
| **`Jcb`**             | `'JCB'`              | JCB card.                    | 0.0.1 |
| **`UnionPay`**        | `'UNION_PAY'`        | UnionPay card.               | 0.0.1 |
| **`Interac`**         | `'INTERAC'`          | Interac card.                | 0.0.1 |
| **`Eftpos`**          | `'EFTPOS'`           | Eftpos card.                 | 0.0.1 |
| **`Other`**           | `'OTHER'`            | Other or unknown card brand. | 0.0.1 |

## FAQ

### Which platforms are supported by this plugin?

The plugin supports Android and iOS. There is no Web implementation, since the Square Mobile Payments SDK requires native hardware access to card readers.

### How can I test payments without a physical card reader?

Use the `showMockReader()` method to display a mock reader interface for testing payment flows without physical hardware. It is only intended for development and testing purposes and is therefore only available in debug builds. You can hide it again with `hideMockReader()`.

### What permissions does the plugin require?

The plugin requires location access to confirm that payments are occurring in a supported Square location, Bluetooth access to connect to Square card readers, and, on iOS, microphone access to receive data from magstripe readers. You can check and request the required permissions with `checkPermissions()` and `requestPermissions()`, and the corresponding privacy descriptions must be added to your `Info.plist` on iOS (see [Installation](#installation)).

### Does the plugin support Tap to Pay on iPhone?

Yes, on iOS you can link a Square seller account with an Apple ID using `linkAppleAccount()`, which presents an Apple sheet with the Tap to Pay on iPhone terms and conditions. Use `isDeviceCapable()` to check whether the device supports Tap to Pay on iPhone, and `relinkAppleAccount()` to switch to a different Apple ID.

### Why do the plugin methods fail before I call any of them?

The Square Mobile Payments SDK must be initialized natively with your Square Application ID before the plugin can be used: in a custom `Application` class on Android and in the `AppDelegate` on iOS (see [Installation](#installation)). Additionally, `initialize(...)` must be called before any other plugin method, followed by `authorize(...)` with a Square access token.

### Can I process payments without an internet connection?

Yes, the plugin supports processing payments online or offline with automatic sync. Note that for offline payments, the payment `id` may be `null` until the payment has been synced.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/): Support in-app purchases in your Capacitor app.
- [Superwall](https://capawesome.io/docs/sdks/capacitor/superwall/): Present remotely-configured paywalls to drive subscriptions.
- [Wallet](https://capawesome.io/docs/sdks/capacitor/wallet/): Add passes to Apple Wallet and Google Wallet.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/square-mobile-payments/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/square-mobile-payments/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Square, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Superwall Plugin

Unofficial Capacitor plugin for [Superwall SDK](https://superwall.com/).[1](#fn:1)

## Features

The Capacitor Superwall plugin brings remotely-configured paywalls and paywall experiments to Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 💰 **Paywall Presentation**: Show beautiful, remotely-configured paywalls to drive subscriptions.
- 🎯 **Feature Gating**: Control feature access based on subscription status.
- 📊 **Analytics Events**: Forward Superwall events to your analytics platform.
- 👤 **User Management**: Identify users, set custom attributes, and manage subscription status.
- 🧪 **A/B Testing**: Built-in support for paywall experiments and holdout groups.
- 🔗 **Deep Linking**: Handle deep links for paywall campaigns.
- 🎨 **Customization**: Configure paywall behavior, logging, and appearance.
- 🤝 **Compatibility**: Works alongside the [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/) and [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Superwall plugin is typically used to monetize an app with subscriptions, for example:

- **Feature gating**: Register a placement with `register(...)` when the user taps a premium feature and present a paywall if they don't have an active subscription.
- **Paywall experiments**: Run A/B tests and holdout groups for your paywalls, configured remotely on the Superwall dashboard without app updates.
- **Personalized paywalls**: Identify users and set custom attributes to target paywalls with audience filters.
- **Analytics forwarding**: Listen for Superwall events and forward them to your analytics platform.
- **Campaign deep links**: Handle deep links for paywall campaigns configured on the dashboard.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-superwall` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-superwall
npx cap sync
```

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$superwallAndroidVersion` version of `com.superwall.sdk:superwall-android` (default: `2.6.6`)

#### Manifest

Add the required activities to your `AndroidManifest.xml` file:

```
<activity
  android:name="com.superwall.sdk.paywall.view.SuperwallPaywallActivity"
  android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar"
  android:configChanges="orientation|screenSize|keyboardHidden">
</activity>
<activity android:name="com.superwall.sdk.debug.DebugViewActivity" />
<activity android:name="com.superwall.sdk.debug.localizations.SWLocalizationActivity" />
<activity android:name="com.superwall.sdk.debug.SWConsoleActivity" />
```

Set your app's theme in the `android:theme` section of the `SuperwallPaywallActivity`.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to configure the SDK, present paywalls, identify users, manage subscription status, handle deep links, and listen for events.

### Configure the SDK

Configure the Superwall SDK with the API key from your dashboard. This must be called once before all other methods:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const configureSuperwall = async () => {
  await Superwall.configure({
    apiKey: 'pk_your_api_key_here',
    options: {
      paywalls: {
        shouldPreload: true,
        automaticallyDismiss: true,
      },
      logging: {
        level: 'WARN',
        scopes: ['ALL'],
      },
    },
  });
};
```

### Present a paywall

Register a placement with `register(...)` to present a paywall if the user doesn't have an active subscription. This is the primary method for feature gating and paywall presentation:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const showPaywall = async () => {
  const result = await Superwall.register({
    placement: 'premium_feature',
    params: {
      user_level: 5,
      source: 'settings',
    },
  });

  console.log('Paywall result:', result.result); // 'PURCHASED', 'CANCELLED', or 'RESTORED'
};
```

### Check whether a paywall would be presented

Use `getPresentationResult(...)` to check if a paywall would be presented for a placement without actually presenting it:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const checkPaywall = async () => {
  const result = await Superwall.getPresentationResult({
    placement: 'premium_feature',
  });

  if (result.type === 'PAYWALL') {
    console.log('Paywall would be shown');
  } else if (result.type === 'NO_AUDIENCE_MATCH') {
    console.log('User does not match audience, no paywall');
  }
};
```

### Identify the user

Identify the current user with a unique ID to link it to their anonymous alias for analytics and paywall assignments:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const identifyUser = async (userId: string) => {
  await Superwall.identify({
    userId: userId,
    options: {
      restorePaywallAssignments: true,
    },
  });
};
```

### Set user attributes

Set custom user attributes for personalization and audience filtering on the Superwall dashboard. Keys starting with `$` are reserved for Superwall use:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const setAttributes = async () => {
  await Superwall.setUserAttributes({
    attributes: {
      username: 'john_doe',
      subscription_tier: 'free',
      total_purchases: 5,
    },
  });
};
```

### Check the subscription status

Read the current subscription status of the user:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const checkSubscription = async () => {
  const result = await Superwall.getSubscriptionStatus();
  console.log('Subscription status:', result.status); // 'ACTIVE', 'INACTIVE', or 'UNKNOWN'
};
```

### Listen for events

Listen for analytics events, subscription status changes, paywall lifecycle events and custom paywall actions:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const addListeners = async () => {
  // Forward analytics events to your platform
  await Superwall.addListener('superwallEvent', (event) => {
    console.log('Superwall event:', event.type, event.data);
    // Forward to your analytics: Analytics.track(event.type, event.data);
  });

  // Track subscription status changes
  await Superwall.addListener('subscriptionStatusDidChange', (event) => {
    console.log('Subscription status changed to:', event.status);
  });

  // Handle paywall lifecycle events
  await Superwall.addListener('paywallPresented', (event) => {
    console.log('Paywall presented:', event.paywallInfo.placement);
  });

  await Superwall.addListener('paywallDismissed', (event) => {
    console.log('Paywall dismissed:', event.paywallInfo.placement);
  });

  // Handle custom paywall actions
  await Superwall.addListener('customPaywallAction', (event) => {
    console.log('Custom action:', event.name);
    // Handle custom actions like 'help', 'contact', etc.
  });
};
```

### Handle a campaign deep link

Process deep links associated with Superwall campaigns configured on the dashboard:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const handleCampaignDeepLink = async (url: string) => {
  await Superwall.handleDeepLink({ url });
};
```

### Reset the user identity on logout

Reset the user identity when the user explicitly logs out:

```
import { Superwall } from '@capawesome/capacitor-superwall';

const logout = async () => {
  await Superwall.reset();
};
```

## API

- [`configure(...)`](#configure)
- [`register(...)`](#register)
- [`dismiss()`](#dismiss)
- [`restorePurchases()`](#restorepurchases)
- [`getPresentationResult(...)`](#getpresentationresult)
- [`identify(...)`](#identify)
- [`reset()`](#reset)
- [`getUserId()`](#getuserid)
- [`getIsLoggedIn()`](#getisloggedin)
- [`setUserAttributes(...)`](#setuserattributes)
- [`handleDeepLink(...)`](#handledeeplink)
- [`getSubscriptionStatus()`](#getsubscriptionstatus)
- [`addListener('superwallEvent', ...)`](#addlistenersuperwallevent-)
- [`addListener('subscriptionStatusDidChange', ...)`](#addlistenersubscriptionstatusdidchange-)
- [`addListener('paywallPresented', ...)`](#addlistenerpaywallpresented-)
- [`addListener('paywallWillDismiss', ...)`](#addlistenerpaywallwilldismiss-)
- [`addListener('paywallDismissed', ...)`](#addlistenerpaywalldismissed-)
- [`addListener('customPaywallAction', ...)`](#addlistenercustompaywallaction-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### configure(...)

```
configure(options: ConfigureOptions) => Promise<void>
```

Configure the Superwall SDK.

This method must be called once before all other methods.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `ConfigureOptions` |

**Since:** 0.0.1

______________________________________________________________________

### register(...)

```
register(options: RegisterOptions) => Promise<RegisterResult>
```

Register a placement and present a paywall if the user doesn't have an active subscription.

This is the primary method for feature gating and paywall presentation. The feature closure will execute based on the gating mode:

- Non-gated: Executes immediately
- Gated: Executes after subscription or if already subscribed

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `RegisterOptions` |

**Returns:** `Promise<RegisterResult>`

**Since:** 0.0.1

______________________________________________________________________

### dismiss()

```
dismiss() => Promise<void>
```

Dismiss the currently presented paywall, if one exists.

Resolves once the paywall has been dismissed. If no paywall is presented, the method resolves immediately.

Only available on Android and iOS.

**Since:** 0.1.3

______________________________________________________________________

### restorePurchases()

```
restorePurchases() => Promise<void>
```

Restore purchases made by the user.

Rejects if the SDK has not been configured or the restore fails. A successful restore does not necessarily mean the user has an active subscription. Use `getSubscriptionStatus()` to check the subscription status after restoring.

Only available on Android and iOS.

**Since:** 0.1.5

______________________________________________________________________

### getPresentationResult(...)

```
getPresentationResult(options: GetPresentationResultOptions) => Promise<GetPresentationResultResult>
```

Check if a paywall would be presented for a placement without actually presenting it.

Useful for determining whether to show a feature or paywall before the user interacts.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `GetPresentationResultOptions` |

**Returns:** `Promise<GetPresentationResultResult>`

**Since:** 0.0.1

______________________________________________________________________

### identify(...)

```
identify(options: IdentifyOptions) => Promise<void>
```

Identify the current user with a unique ID.

This links the user ID to their anonymous alias for analytics and paywall assignments.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `IdentifyOptions` |

**Since:** 0.0.1

______________________________________________________________________

### reset()

```
reset() => Promise<void>
```

Reset the user identity.

This rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download configuration. Should only be called on explicit logout.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### getUserId()

```
getUserId() => Promise<GetUserIdResult>
```

Get the current user ID.

Returns the identified user ID if set, otherwise returns the anonymous ID.

Only available on Android and iOS.

**Returns:** `Promise<GetUserIdResult>`

**Since:** 0.0.1

______________________________________________________________________

### getIsLoggedIn()

```
getIsLoggedIn() => Promise<GetIsLoggedInResult>
```

Check if the user is logged in (identified).

Only available on Android and iOS.

**Returns:** `Promise<GetIsLoggedInResult>`

**Since:** 0.0.1

______________________________________________________________________

### setUserAttributes(...)

```
setUserAttributes(options: SetUserAttributesOptions) => Promise<void>
```

Set custom user attributes for personalization and audience filtering.

Attributes can be used in audience filters on the Superwall dashboard. Keys starting with `$` are reserved for Superwall use. Arrays and nested structures are not supported. Set values to null to remove attributes.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `SetUserAttributesOptions` |

**Since:** 0.0.1

______________________________________________________________________

### handleDeepLink(...)

```
handleDeepLink(options: HandleDeepLinkOptions) => Promise<void>
```

Handle a deep link URL for paywall campaigns.

This processes deep links associated with Superwall campaigns configured on the dashboard.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `HandleDeepLinkOptions` |

**Since:** 0.0.1

______________________________________________________________________

### getSubscriptionStatus()

```
getSubscriptionStatus() => Promise<GetSubscriptionStatusResult>
```

Get the current subscription status.

Only available on Android and iOS.

**Returns:** `Promise<GetSubscriptionStatusResult>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('superwallEvent', ...)

```
addListener(eventName: 'superwallEvent', listenerFunc: (event: SuperwallEventInfo) => void) => Promise<PluginListenerHandle>
```

Add a listener for Superwall analytics events.

These events can be forwarded to your analytics platform.

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'superwallEvent'`                    |
| **`listenerFunc`** | `(event: SuperwallEventInfo) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('subscriptionStatusDidChange', ...)

```
addListener(eventName: 'subscriptionStatusDidChange', listenerFunc: (event: SubscriptionStatusDidChangeEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for subscription status changes.

Only available on Android and iOS.

| Param              | Type                                                |
| ------------------ | --------------------------------------------------- |
| **`eventName`**    | `'subscriptionStatusDidChange'`                     |
| **`listenerFunc`** | `(event: SubscriptionStatusDidChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paywallPresented', ...)

```
addListener(eventName: 'paywallPresented', listenerFunc: (event: PaywallPresentedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when a paywall is presented.

Only available on Android and iOS.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'paywallPresented'`                     |
| **`listenerFunc`** | `(event: PaywallPresentedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paywallWillDismiss', ...)

```
addListener(eventName: 'paywallWillDismiss', listenerFunc: (event: PaywallWillDismissEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when a paywall will dismiss.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'paywallWillDismiss'`                     |
| **`listenerFunc`** | `(event: PaywallWillDismissEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('paywallDismissed', ...)

```
addListener(eventName: 'paywallDismissed', listenerFunc: (event: PaywallDismissedEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for when a paywall is dismissed.

Only available on Android and iOS.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'paywallDismissed'`                     |
| **`listenerFunc`** | `(event: PaywallDismissedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('customPaywallAction', ...)

```
addListener(eventName: 'customPaywallAction', listenerFunc: (event: CustomPaywallActionEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for custom paywall actions.

Triggered when a user taps an element with the `data-pw-custom` attribute.

Only available on Android and iOS.

| Param              | Type                                        |
| ------------------ | ------------------------------------------- |
| **`eventName`**    | `'customPaywallAction'`                     |
| **`listenerFunc`** | `(event: CustomPaywallActionEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### ConfigureOptions

| Prop          | Type               | Description                                 | Since |
| ------------- | ------------------ | ------------------------------------------- | ----- |
| **`apiKey`**  | `string`           | The Superwall API key from your dashboard.  | 0.0.1 |
| **`options`** | `SuperwallOptions` | Optional configuration options for the SDK. | 0.0.1 |

#### SuperwallOptions

| Prop                                  | Type                 | Description                                                                          | Default                      | Since |
| ------------------------------------- | -------------------- | ------------------------------------------------------------------------------------ | ---------------------------- | ----- |
| **`paywalls`**                        | `PaywallOptions`     | Paywall presentation and behavior options.                                           |                              | 0.0.1 |
| **`logging`**                         | `LoggingOptions`     | Logging configuration.                                                               |                              | 0.0.1 |
| **`networkEnvironment`**              | `NetworkEnvironment` | Network environment for API requests.                                                | `NetworkEnvironment.Release` | 0.0.1 |
| **`localeIdentifier`**                | `string`             | Override the locale identifier for localization.                                     |                              | 0.0.1 |
| **`shouldObservePurchases`**          | `boolean`            | Observe external Google Play purchases. Only available on Android.                   | `true`                       | 0.0.1 |
| **`isExternalDataCollectionEnabled`** | `boolean`            | Enable or disable external data collection for analytics. Only available on Android. | `true`                       | 0.0.1 |

#### PaywallOptions

| Prop                                 | Type      | Description                                           | Default | Since |
| ------------------------------------ | --------- | ----------------------------------------------------- | ------- | ----- |
| **`isHapticFeedbackEnabled`**        | `boolean` | Enable haptic feedback on paywall interactions.       | `true`  | 0.0.1 |
| **`shouldShowPurchaseFailureAlert`** | `boolean` | Show an alert when purchase restoration fails.        | `true`  | 0.0.1 |
| **`shouldPreload`**                  | `boolean` | Preload paywalls during SDK initialization.           | `true`  | 0.0.1 |
| **`automaticallyDismiss`**           | `boolean` | Automatically dismiss paywall on purchase or restore. | `true`  | 0.0.1 |

#### LoggingOptions

| Prop         | Type         | Description                 | Default          | Since |
| ------------ | ------------ | --------------------------- | ---------------- | ----- |
| **`level`**  | `LogLevel`   | The log level for SDK logs. | `LogLevel.Warn`  | 0.0.1 |
| **`scopes`** | `LogScope[]` | The log scopes to enable.   | `[LogScope.All]` | 0.0.1 |

#### RegisterResult

| Prop         | Type            | Description                             | Since |
| ------------ | --------------- | --------------------------------------- | ----- |
| **`result`** | `PaywallResult` | The result of the paywall presentation. | 0.0.1 |

#### RegisterOptions

| Prop            | Type                  | Description                                                                                        | Since |
| --------------- | --------------------- | -------------------------------------------------------------------------------------------------- | ----- |
| **`placement`** | `string`              | The placement identifier configured in the Superwall dashboard.                                    | 0.0.1 |
| **`params`**    | `Record<string, any>` | Optional parameters for audience filtering. Keys starting with `$` are reserved for Superwall use. | 0.0.1 |

#### GetPresentationResultResult

| Prop             | Type                     | Description                                                                  | Since |
| ---------------- | ------------------------ | ---------------------------------------------------------------------------- | ----- |
| **`type`**       | `PresentationResultType` | The type of presentation result.                                             | 0.0.1 |
| **`experiment`** | `Experiment`             | [Experiment](#experiment) information if the result is a paywall or holdout. | 0.0.1 |

#### Experiment

| Prop          | Type     | Description                               | Since |
| ------------- | -------- | ----------------------------------------- | ----- |
| **`id`**      | `string` | The unique identifier for the experiment. | 0.0.1 |
| **`variant`** | `string` | The variant assigned to the user.         | 0.0.1 |

#### GetPresentationResultOptions

| Prop            | Type                  | Description                                 | Since |
| --------------- | --------------------- | ------------------------------------------- | ----- |
| **`placement`** | `string`              | The placement identifier to check.          | 0.0.1 |
| **`params`**    | `Record<string, any>` | Optional parameters for audience filtering. | 0.0.1 |

#### IdentifyOptions

| Prop          | Type                    | Description                              | Since |
| ------------- | ----------------------- | ---------------------------------------- | ----- |
| **`userId`**  | `string`                | The unique user ID to identify the user. | 0.0.1 |
| **`options`** | `IdentifyOptionsConfig` | Additional options for identification.   | 0.0.1 |

#### IdentifyOptionsConfig

| Prop                            | Type      | Description                                                                                              | Default | Since |
| ------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`restorePaywallAssignments`** | `boolean` | Restore paywall assignments from the server. Set to true when switching accounts to restore assignments. | `false` | 0.0.1 |

#### GetUserIdResult

| Prop         | Type     | Description                                    | Since |
| ------------ | -------- | ---------------------------------------------- | ----- |
| **`userId`** | `string` | The current user ID (identified or anonymous). | 0.0.1 |

#### GetIsLoggedInResult

| Prop             | Type      | Description                                 | Since |
| ---------------- | --------- | ------------------------------------------- | ----- |
| **`isLoggedIn`** | `boolean` | Whether the user is logged in (identified). | 0.0.1 |

#### SetUserAttributesOptions

| Prop             | Type                  | Description                                                                                                       | Since |
| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`attributes`** | `Record<string, any>` | User attributes as key-value pairs. Keys starting with `$` are reserved. Set values to null to remove attributes. | 0.0.1 |

#### HandleDeepLinkOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`url`** | `string` | The deep link URL to handle. | 0.0.1 |

#### GetSubscriptionStatusResult

| Prop         | Type                 | Description                      | Since |
| ------------ | -------------------- | -------------------------------- | ----- |
| **`status`** | `SubscriptionStatus` | The current subscription status. | 0.0.1 |

#### PluginListenerHandle

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

#### SuperwallEventInfo

| Prop       | Type                  | Description                               | Since |
| ---------- | --------------------- | ----------------------------------------- | ----- |
| **`type`** | `SuperwallEventType`  | The type of Superwall event.              | 0.0.1 |
| **`data`** | `Record<string, any>` | Additional event data as key-value pairs. | 0.0.1 |

#### SubscriptionStatusDidChangeEvent

| Prop         | Type                 | Description                  | Since |
| ------------ | -------------------- | ---------------------------- | ----- |
| **`status`** | `SubscriptionStatus` | The new subscription status. | 0.0.1 |

#### PaywallPresentedEvent

| Prop              | Type          | Description                              | Since |
| ----------------- | ------------- | ---------------------------------------- | ----- |
| **`paywallInfo`** | `PaywallInfo` | Information about the presented paywall. | 0.0.1 |

#### PaywallInfo

| Prop             | Type                  | Description                                                                  | Since |
| ---------------- | --------------------- | ---------------------------------------------------------------------------- | ----- |
| **`id`**         | `string`              | The unique identifier for the paywall.                                       | 0.0.1 |
| **`placement`**  | `string`              | The placement identifier.                                                    | 0.0.1 |
| **`experiment`** | `Experiment`          | [Experiment](#experiment) information if the paywall is part of an A/B test. | 0.0.1 |
| **`data`**       | `Record<string, any>` | Additional paywall metadata.                                                 | 0.0.1 |

#### PaywallWillDismissEvent

| Prop              | Type          | Description                                    | Since |
| ----------------- | ------------- | ---------------------------------------------- | ----- |
| **`paywallInfo`** | `PaywallInfo` | Information about the paywall being dismissed. | 0.0.1 |

#### PaywallDismissedEvent

| Prop              | Type          | Description                              | Since |
| ----------------- | ------------- | ---------------------------------------- | ----- |
| **`paywallInfo`** | `PaywallInfo` | Information about the dismissed paywall. | 0.0.1 |

#### CustomPaywallActionEvent

| Prop       | Type     | Description                    | Since |
| ---------- | -------- | ------------------------------ | ----- |
| **`name`** | `string` | The name of the custom action. | 0.0.1 |

### Enums

#### LogLevel

| Members     | Value     | Description            | Since |
| ----------- | --------- | ---------------------- | ----- |
| **`Debug`** | `'DEBUG'` | Debug level logging.   | 0.0.1 |
| **`Info`**  | `'INFO'`  | Info level logging.    | 0.0.1 |
| **`Warn`**  | `'WARN'`  | Warning level logging. | 0.0.1 |
| **`Error`** | `'ERROR'` | Error level logging.   | 0.0.1 |

#### LogScope

| Members         | Value         | Description                 | Since |
| --------------- | ------------- | --------------------------- | ----- |
| **`All`**       | `'ALL'`       | All log scopes.             | 0.0.1 |
| **`Analytics`** | `'ANALYTICS'` | Analytics related logs.     | 0.0.1 |
| **`Config`**    | `'CONFIG'`    | Configuration related logs. | 0.0.1 |
| **`Events`**    | `'EVENTS'`    | Event tracking logs.        | 0.0.1 |
| **`Paywalls`**  | `'PAYWALLS'`  | Paywall related logs.       | 0.0.1 |
| **`Purchases`** | `'PURCHASES'` | Purchase related logs.      | 0.0.1 |

#### NetworkEnvironment

| Members         | Value         | Description                          | Since |
| --------------- | ------------- | ------------------------------------ | ----- |
| **`Release`**   | `'RELEASE'`   | Production environment.              | 0.0.1 |
| **`Developer`** | `'DEVELOPER'` | Development environment for testing. | 0.0.1 |

#### PaywallResult

| Members         | Value         | Description                 | Since |
| --------------- | ------------- | --------------------------- | ----- |
| **`Purchased`** | `'PURCHASED'` | User completed a purchase.  | 0.0.1 |
| **`Cancelled`** | `'CANCELLED'` | User cancelled the paywall. | 0.0.1 |
| **`Restored`**  | `'RESTORED'`  | User restored purchases.    | 0.0.1 |

#### PresentationResultType

| Members                   | Value                     | Description                             | Since |
| ------------------------- | ------------------------- | --------------------------------------- | ----- |
| **`PlacementNotFound`**   | `'PLACEMENT_NOT_FOUND'`   | The placement was not found.            | 0.0.1 |
| **`NoAudienceMatch`**     | `'NO_AUDIENCE_MATCH'`     | No audience matched for this placement. | 0.0.1 |
| **`Paywall`**             | `'PAYWALL'`               | A paywall would be presented.           | 0.0.1 |
| **`Holdout`**             | `'HOLDOUT'`               | User is in a holdout group.             | 0.0.1 |
| **`PaywallNotAvailable`** | `'PAYWALL_NOT_AVAILABLE'` | Paywall is not available.               | 0.0.1 |

#### SubscriptionStatus

| Members        | Value        | Description                                | Since |
| -------------- | ------------ | ------------------------------------------ | ----- |
| **`Unknown`**  | `'UNKNOWN'`  | Subscription status is unknown.            | 0.0.1 |
| **`Active`**   | `'ACTIVE'`   | User has an active subscription.           | 0.0.1 |
| **`Inactive`** | `'INACTIVE'` | User does not have an active subscription. | 0.0.1 |

#### SuperwallEventType

| Members                           | Value                              | Description                  | Since |
| --------------------------------- | ---------------------------------- | ---------------------------- | ----- |
| **`FirstSeen`**                   | `'FIRST_SEEN'`                     | First time user is seen.     | 0.0.1 |
| **`AppOpen`**                     | `'APP_OPEN'`                       | App was opened.              | 0.0.1 |
| **`AppLaunch`**                   | `'APP_LAUNCH'`                     | App was launched.            | 0.0.1 |
| **`AppClose`**                    | `'APP_CLOSE'`                      | App was closed.              | 0.0.1 |
| **`SessionStart`**                | `'SESSION_START'`                  | Session started.             | 0.0.1 |
| **`DeepLink`**                    | `'DEEP_LINK'`                      | Deep link was opened.        | 0.0.1 |
| **`TriggerFire`**                 | `'TRIGGER_FIRE'`                   | Trigger was fired.           | 0.0.1 |
| **`PaywallOpen`**                 | `'PAYWALL_OPEN'`                   | Paywall was opened.          | 0.0.1 |
| **`PaywallClose`**                | `'PAYWALL_CLOSE'`                  | Paywall was closed.          | 0.0.1 |
| **`PaywallDecline`**              | `'PAYWALL_DECLINE'`                | Paywall was declined.        | 0.0.1 |
| **`TransactionStart`**            | `'TRANSACTION_START'`              | Transaction started.         | 0.0.1 |
| **`TransactionComplete`**         | `'TRANSACTION_COMPLETE'`           | Transaction completed.       | 0.0.1 |
| **`TransactionFail`**             | `'TRANSACTION_FAIL'`               | Transaction failed.          | 0.0.1 |
| **`TransactionAbandon`**          | `'TRANSACTION_ABANDON'`            | Transaction was abandoned.   | 0.0.1 |
| **`TransactionRestore`**          | `'TRANSACTION_RESTORE'`            | Transaction restore.         | 0.0.1 |
| **`TransactionTimeout`**          | `'TRANSACTION_TIMEOUT'`            | Transaction timeout.         | 0.0.1 |
| **`SubscriptionStart`**           | `'SUBSCRIPTION_START'`             | Subscription started.        | 0.0.1 |
| **`FreeTrialStart`**              | `'FREE_TRIAL_START'`               | Free trial started.          | 0.0.1 |
| **`SubscriptionStatusDidChange`** | `'SUBSCRIPTION_STATUS_DID_CHANGE'` | Subscription status changed. | 0.0.1 |

## FAQ

### Which platforms are supported by this plugin?

The plugin supports Android and iOS. There is no Web implementation, since the Superwall SDK targets native mobile apps.

### Do I need to call `configure` before using other methods?

Yes, `configure(...)` must be called once with the Superwall API key from your dashboard before all other methods. You can optionally pass configuration options for paywall behavior, logging, and the network environment.

### What is the difference between `register` and `getPresentationResult`?

The `register(...)` method registers a placement and actually presents a paywall if the user doesn't have an active subscription. The `getPresentationResult(...)` method only checks whether a paywall would be presented for a placement without presenting it, which is useful for deciding whether to show a feature or a paywall before the user interacts.

### When should I call `reset`?

Call `reset()` only on explicit logout. It rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download its configuration. To identify a new user afterwards, use `identify(...)`.

### How do I forward Superwall events to my analytics platform?

Add a listener for the `superwallEvent` event. It emits Superwall analytics events such as paywall opens, transactions, and subscription starts, together with additional event data that you can pass to your analytics platform. See [Listen for events](#listen-for-events) above for an example.

### Is this an official Superwall plugin?

No, this is an unofficial Capacitor plugin for the Superwall SDK maintained by Capawesome. It is not affiliated with, endorsed by, or sponsored by the makers of Superwall.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Review](https://capawesome.io/docs/sdks/capacitor/app-review/): Let users submit app store reviews and ratings.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Track events and analyze user behavior with PostHog.
- [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/): Support in-app purchases in your Capacitor app.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/superwall/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/superwall/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Nest 22, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor System WebView Plugin

Capacitor plugin to detect an outdated Android System WebView and guide users to update it.

## Features

- 🔍 **Detection**: Read the package name and version of the active Android System WebView provider.
- ⚠️ **Outdated check**: Compare the installed Chromium major version against the minimum your app requires.
- 🛒 **Update flow**: Send users straight to the Play Store entry of their active WebView provider.
- 🤝 **Compatibility**: Works alongside the [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/), [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/) and [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The System WebView plugin is typically used to protect an app against outdated Android System WebViews, for example:

- **Update checks on app start**: Check with `isUpdateRequired(...)` whether the installed WebView meets the minimum Chromium version your app's bundle requires.
- **Guided update flows**: Prompt the user with a dialog and send them straight to the Play Store entry of their active WebView provider with `openAppStore()`.
- **Support diagnostics**: Read the package name and version of the active WebView provider with `getInfo()` and attach it to bug reports to explain hard-to-diagnose rendering issues.
- **Feature gating**: Only enable web features like CSS `:has()` or container queries when the installed WebView is recent enough to support them.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-system-webview` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-system-webview
npx cap sync
```

This plugin is only available on **Android**. On iOS and Web, all methods reject as unimplemented (see [iOS](#ios) below).

### Android

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidxWebkitVersion` version of `androidx.webkit:webkit` (default: `1.14.0`)

### iOS

This plugin has **no iOS implementation** and does not need one. On iOS, the `WKWebView` is part of the operating system and is updated together with iOS itself. It cannot be updated separately, so there is nothing for an app to detect or fix.

All methods reject as unimplemented on iOS.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to prompt the user to update the WebView and read information about the WebView provider.

### Prompt the user to update the WebView

The recommended pattern is to check whether an update is required on app start, prompt the user with the [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) plugin, and then open the Play Store. Only available on Android:

```
import { SystemWebview } from '@capawesome/capacitor-system-webview';
import { Dialog } from '@capacitor/dialog';

const promptForUpdateIfRequired = async () => {
  const { required } = await SystemWebview.isUpdateRequired({
    minMajorVersion: 105,
  });
  if (!required) {
    return;
  }
  const { value } = await Dialog.confirm({
    title: 'Update required',
    message:
      'Your Android System WebView is outdated. Please update it to continue using all features of this app.',
    okButtonTitle: 'Update',
  });
  if (value) {
    await SystemWebview.openAppStore();
  }
};
```

> [!NOTE] A WebView update only takes effect the next time the app process is started. The currently running app keeps using the old WebView until it is restarted.

### Read information about the WebView provider

Get the package name, version name and Chromium major version of the active WebView provider, for example to attach it to your support diagnostics. Only available on Android:

```
import { SystemWebview } from '@capawesome/capacitor-system-webview';

const getInfo = async () => {
  const info = await SystemWebview.getInfo();
  return info;
};
```

## API

- [`getInfo()`](#getinfo)
- [`isUpdateRequired(...)`](#isupdaterequired)
- [`openAppStore()`](#openappstore)
- [Interfaces](#interfaces)

### getInfo()

```
getInfo() => Promise<GetInfoResult>
```

Get information about the active Android System WebView provider.

Only available on Android.

**Returns:** `Promise<GetInfoResult>`

**Since:** 0.1.0

______________________________________________________________________

### isUpdateRequired(...)

```
isUpdateRequired(options: IsUpdateRequiredOptions) => Promise<IsUpdateRequiredResult>
```

Check whether the active Android System WebView is older than the minimum Chromium major version required by your app.

Only available on Android.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `IsUpdateRequiredOptions` |

**Returns:** `Promise<IsUpdateRequiredResult>`

**Since:** 0.1.0

______________________________________________________________________

### openAppStore()

```
openAppStore() => Promise<void>
```

Open the Play Store entry of the active Android System WebView provider so the user can update it.

Only available on Android.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetInfoResult

| Prop               | Type     | Description                                      | Since                                                                                                                                                                                                                                                             |
| ------------------ | -------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`majorVersion`** | \`number | null\`                                           | The Chromium major version of the active WebView provider. This is the integer before the first dot of the `versionName` (e.g. `126` for `126.0.6478.122`). `null` if the `versionName` is not a Chromium-style version, which can happen with OEM WebView forks. |
| **`packageName`**  | `string` | The package name of the active WebView provider. | 0.1.0                                                                                                                                                                                                                                                             |
| **`versionName`**  | `string` | The version name of the active WebView provider. | 0.1.0                                                                                                                                                                                                                                                             |

#### IsUpdateRequiredResult

| Prop           | Type      | Description                                                                                 | Since |
| -------------- | --------- | ------------------------------------------------------------------------------------------- | ----- |
| **`required`** | `boolean` | `true` if the active WebView is older than the required minimum version, otherwise `false`. | 0.1.0 |

#### IsUpdateRequiredOptions

| Prop                  | Type     | Description                                                                                                                                     | Since |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`minMajorVersion`** | `number` | The minimum Chromium major version your app requires. The active WebView is considered outdated if its `majorVersion` is lower than this value. | 0.1.0 |

## Why Outdated System WebViews Matter

On Android, your Capacitor app runs inside the Android System WebView, which is updated independently of the operating system. Many devices run an ancient WebView because the user has disabled automatic updates, is offline, or uses a custom ROM. When that happens, modern web features your app relies on may simply be missing, causing hard-to-diagnose "the app is broken" support tickets.

Because "outdated" depends on which web features your app's bundle actually needs, this plugin never hardcodes a threshold. Instead, your app declares the minimum Chromium major version it requires via `isUpdateRequired(...)`.

The following table gives a rough idea of when some popular web features became available in Chromium (and therefore the System WebView):

| Chromium major | Rough web-feature baseline                  |
| -------------- | ------------------------------------------- |
| 97+            | Array `findLast` / `findLastIndex`          |
| 105+           | CSS `:has()` selector and container queries |
| 112+           | Native CSS nesting                          |
| 114+           | CSS `text-wrap: balance`                    |

Pick the minimum version based on the features your app uses and pass it as `minMajorVersion`.

## FAQ

### How is this plugin different from other similar plugins?

It turns a hard-to-diagnose class of Android bugs into something you can detect and fix: read the active WebView provider's package name, version, and Chromium major version, compare it against the minimum your app's bundle needs, and send users straight to the Play Store entry of their own WebView provider to update it. Your app declares the minimum Chromium version it requires, so the check always matches the web features your bundle actually uses. The API is fully typed and kept current with the latest Capacitor version.

### Why is this plugin not available on iOS?

On iOS, the `WKWebView` is part of the operating system and is updated together with iOS itself. It cannot be updated separately, so there is nothing for an app to detect or fix. All methods therefore reject as unimplemented on iOS and Web.

### Which minimum Chromium version should I require?

There is no universal threshold, because "outdated" depends on which web features your app's bundle actually needs. Pick the minimum Chromium major version based on the features your app uses (for example, CSS `:has()` and container queries require Chromium 105 or newer) and pass it as `minMajorVersion` to `isUpdateRequired(...)`. See [Why Outdated System WebViews Matter](#why-outdated-system-webviews-matter) for a rough feature baseline table.

### Why is `majorVersion` sometimes `null`?

The `majorVersion` is derived from the integer before the first dot of the WebView provider's `versionName`. If the `versionName` is not a Chromium-style version, which can happen with OEM WebView forks, the `majorVersion` is `null`. In that case, you can still inspect the raw `packageName` and `versionName` returned by `getInfo()`.

### Why does my app still use the old WebView after the user updated it?

A WebView update only takes effect the next time the app process is started. The currently running app keeps using the old WebView until it is restarted.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist with native app updates.
- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, and operating system.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Show native alert, confirm, and prompt dialogs.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/system-webview/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/system-webview/LICENSE).

# Capacitor Tab Bar Plugin

Capacitor plugin to display a native [tab bar](https://developer.apple.com/documentation/uikit/uitabbar) with Liquid Glass on iOS.

## Features

- 🫧 **Liquid Glass**: Renders the native Liquid Glass tab bar on iOS 26 and the classic tab bar on earlier versions.
- 🧭 **Tabs**: Use SF Symbols or images from your asset catalog as icons and show badges.
- 🎨 **Colors**: Customize the colors of the selected and unselected tabs.
- 📐 **Safe area**: Extends the bottom safe area inset of the web view, so your content is never covered by the tab bar.
- 🚀 **Launch configuration**: Show the tab bar from launch without waiting for your web app.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| iOS |
| --- |
|     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-tab-bar` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-tab-bar
npx cap sync
```

This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented.

### iOS

The tab bar is placed on top of the web view and the bottom safe area inset of the web view is increased by the height of the tab bar. Your web app must meet the following requirements so that its content is not covered by the tab bar:

- The `viewport` meta tag of your page must contain `viewport-fit=cover`:

```
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
```

- The [`ios.contentInset`](https://capacitorjs.com/docs/config) configuration option must be set to `never` (default). With `always`, the inset is applied twice.
- Your content must respect the bottom safe area inset, for example using `padding-bottom: env(safe-area-inset-bottom)`.

If you use [`@capacitor/splash-screen`](https://capacitorjs.com/docs/apis/splash-screen), do not configure the `tabs` in your Capacitor configuration, as the tab bar would be displayed on top of the splash screen. Instead, call `setTabs(...)` and `show()` after `SplashScreen.hide()`.

## Configuration

These configuration values are available:

| Prop                  | Type     | Description                                                                                                                                                                                                                                | Since |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`tabs`**            | `Tab[]`  | The tabs to display at launch. If set, the tab bar is created and visible from launch. Do not set this option if you use `@capacitor/splash-screen`, as the tab bar would be displayed on top of the splash screen. Only available on iOS. | 0.1.0 |
| **`selectedTabId`**   | `string` | The ID of the tab to select at launch. If not set, the first tab is selected. Only available on iOS.                                                                                                                                       | 0.1.0 |
| **`selectedColor`**   | `string` | The color of the selected tab as a hex color code. If not set, the system default is used. Only available on iOS.                                                                                                                          | 0.1.0 |
| **`unselectedColor`** | `string` | The color of the unselected tabs as a hex color code. If not set, the system default is used. Has no effect on iOS 26 and later, as the system determines the color of the unselected tabs on Liquid Glass. Only available on iOS.         | 0.1.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "TabBar": {
      "tabs": [{ "id": "home", "title": "Home", "systemImage": "house.fill" }],
      "selectedTabId": "home",
      "selectedColor": "#007AFF",
      "unselectedColor": "#8E8E93"
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome/capacitor-tab-bar" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    TabBar: {
      tabs: [{ "id": "home", "title": "Home", "systemImage": "house.fill" }],
      selectedTabId: "home",
      selectedColor: "#007AFF",
      unselectedColor: "#8E8E93",
    },
  },
};

export default config;
```

## Usage

The following examples show how to set up the tab bar and react to tab selections.

### Set the tabs and show the tab bar

Set the tabs and show the tab bar. Each tab uses either an SF Symbol (`systemImage`) or an image from the asset catalog of your app (`image`) as its icon. Only available on iOS:

```
import { TabBar } from '@capawesome/capacitor-tab-bar';

const showTabBar = async () => {
  await TabBar.setTabs({
    tabs: [
      { id: 'home', title: 'Home', systemImage: 'house.fill' },
      { id: 'search', title: 'Search', systemImage: 'magnifyingglass' },
      { id: 'inbox', title: 'Inbox', systemImage: 'tray.fill', badge: '3' },
      { id: 'profile', title: 'Profile', image: 'profile-icon' },
    ],
    selectedTabId: 'home',
  });
  await TabBar.show();
};

const hideTabBar = async () => {
  await TabBar.hide();
};
```

Alternatively, configure the tabs in your Capacitor configuration to show the tab bar from launch (see [Configuration](#configuration)).

### Listen for tab selections

The `tabSelected` event is emitted every time the user taps a tab, including the tab that is already selected. Only available on iOS:

```
import { TabBar } from '@capawesome/capacitor-tab-bar';

const addListener = async () => {
  await TabBar.addListener('tabSelected', event => {
    console.log('Tab selected:', event.id);
  });
};
```

### Select a tab programmatically

Select a tab, for example after navigating within your web app. This method does not emit the `tabSelected` event. Only available on iOS:

```
import { TabBar } from '@capawesome/capacitor-tab-bar';

const selectTab = async () => {
  await TabBar.selectTabById({ id: 'search' });
};
```

### Update a badge

Call `setTabs(...)` again with the updated tabs. The currently selected tab stays selected. Only available on iOS:

```
import { TabBar } from '@capawesome/capacitor-tab-bar';

const updateBadge = async () => {
  await TabBar.setTabs({
    tabs: [
      { id: 'home', title: 'Home', systemImage: 'house.fill' },
      { id: 'search', title: 'Search', systemImage: 'magnifyingglass' },
      { id: 'inbox', title: 'Inbox', systemImage: 'tray.fill', badge: '4' },
      { id: 'profile', title: 'Profile', image: 'profile-icon' },
    ],
  });
};
```

### Customize the colors

Set the colors of the selected and unselected tabs. Colors that are not provided are reset to the system default. On iOS 26 and later, the unselected color has no effect, as the system determines the color of the unselected tabs on Liquid Glass. Only available on iOS:

```
import { TabBar } from '@capawesome/capacitor-tab-bar';

const setColors = async () => {
  await TabBar.setColors({
    selectedColor: '#FF2D55',
    unselectedColor: '#8E8E93',
  });
};
```

## Ionic Framework

If you use [Ionic Framework](https://ionicframework.com/), you can replace the `ion-tab-bar` with the native tab bar on iOS and keep using the Ionic router for navigation:

1. Hide the `ion-tab-bar` on iOS:

```
.plt-ios ion-tab-bar {
  display: none;
}
```

1. Navigate to the tapped tab using the router and select the native tab whenever the route changes to another tab. Use the same IDs for the native tabs as for the `tab` property of your `ion-tab-button` elements. The following example uses Angular, but the same approach works with React and Vue:

```
<ion-tabs (ionTabsDidChange)="handleTabsDidChange($event)">
  <!-- ... -->
</ion-tabs>
```

```
import { Component, OnInit } from '@angular/core';
import { Router } from '@angular/router';
import { Capacitor } from '@capacitor/core';
import { TabBar } from '@capawesome/capacitor-tab-bar';

@Component({
  selector: 'app-tabs',
  templateUrl: 'tabs.page.html',
})
export class TabsPage implements OnInit {
  private readonly isIos = Capacitor.getPlatform() === 'ios';

  constructor(private readonly router: Router) {}

  ngOnInit() {
    if (this.isIos) {
      void TabBar.addListener('tabSelected', ({ id }) => {
        void this.router.navigateByUrl(`/tabs/${id}`);
      });
    }
  }

  handleTabsDidChange(event: { tab: string }) {
    if (this.isIos) {
      void TabBar.selectTabById({ id: event.tab });
    }
  }
}
```

1. Pad your content with the bottom safe area inset, which includes the height of the native tab bar:

```
ion-content {
  --padding-bottom: env(safe-area-inset-bottom);
}
```

## API

- [`hide()`](#hide)
- [`selectTabById(...)`](#selecttabbyid)
- [`setColors(...)`](#setcolors)
- [`setTabs(...)`](#settabs)
- [`show()`](#show)
- [`addListener('tabSelected', ...)`](#addlistenertabselected-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### hide()

```
hide() => Promise<void>
```

Hide the tab bar.

The tabs are kept and the bottom safe area inset is reset.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### selectTabById(...)

```
selectTabById(options: SelectTabByIdOptions) => Promise<void>
```

Select the tab with the given ID.

This method does not emit the `tabSelected` event.

Only available on iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SelectTabByIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setColors(...)

```
setColors(options: SetColorsOptions) => Promise<void>
```

Set the colors of the tabs.

Colors that are not provided are reset to the system default.

Only available on iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetColorsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setTabs(...)

```
setTabs(options: SetTabsOptions) => Promise<void>
```

Set the tabs of the tab bar.

This replaces all existing tabs. The tab with the ID `selectedTabId` is selected if provided. Otherwise, the currently selected tab stays selected if its ID still exists, or the first tab is selected.

This method does not change the visibility of the tab bar.

Only available on iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `SetTabsOptions` |

**Since:** 0.1.0

______________________________________________________________________

### show()

```
show() => Promise<void>
```

Show the tab bar.

The tab bar is placed at the bottom of the screen and the bottom safe area inset of the web view is increased by the height of the tab bar.

The tabs must be set first using `setTabs(...)` or the `tabs` configuration.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('tabSelected', ...)

```
addListener(eventName: 'tabSelected', listenerFunc: (event: TabSelectedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the user taps a tab.

This event is also emitted if the user taps the tab that is already selected.

Only available on iOS.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'tabSelected'`                     |
| **`listenerFunc`** | `(event: TabSelectedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### SelectTabByIdOptions

| Prop     | Type     | Description                  | Since |
| -------- | -------- | ---------------------------- | ----- |
| **`id`** | `string` | The ID of the tab to select. | 0.1.0 |

#### SetColorsOptions

| Prop                  | Type     | Description                                                                                                                                                                                                      | Since |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`selectedColor`**   | `string` | The color of the selected tab as a hex color code. If not provided, the system default is used.                                                                                                                  | 0.1.0 |
| **`unselectedColor`** | `string` | The color of the unselected tabs as a hex color code. If not provided, the system default is used. Has no effect on iOS 26 and later, as the system determines the color of the unselected tabs on Liquid Glass. | 0.1.0 |

#### SetTabsOptions

| Prop                | Type     | Description                                                                                                                                           | Since |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`tabs`**          | `Tab[]`  | The tabs to display. Each tab must have a unique ID.                                                                                                  | 0.1.0 |
| **`selectedTabId`** | `string` | The ID of the tab to select. If not provided, the currently selected tab stays selected if its ID still exists. Otherwise, the first tab is selected. | 0.1.0 |

#### Tab

| Prop              | Type     | Description                                                                                                                                                                              | Since |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**          | `string` | The unique ID of the tab.                                                                                                                                                                | 0.1.0 |
| **`title`**       | `string` | The title of the tab.                                                                                                                                                                    | 0.1.0 |
| **`systemImage`** | `string` | The name of an SF Symbol to use as the icon of the tab. Exactly one of `systemImage` or `image` must be provided.                                                                        | 0.1.0 |
| **`image`**       | `string` | The name of an image in the asset catalog of the app to use as the icon of the tab. The image is rendered as a template image. Exactly one of `systemImage` or `image` must be provided. | 0.1.0 |
| **`badge`**       | `string` | The badge value of the tab. If not provided, no badge is shown.                                                                                                                          | 0.1.0 |

#### PluginListenerHandle

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

#### TabSelectedEvent

| Prop     | Type     | Description                        | Since |
| -------- | -------- | ---------------------------------- | ----- |
| **`id`** | `string` | The ID of the tab that was tapped. | 0.1.0 |

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/tab-bar/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/tab-bar/LICENSE).

# Capacitor Tauri Platform

Capacitor platform to build, run, and package lean, secure desktop apps for macOS, Windows, and Linux with Tauri.[1](#fn:1)

## Features

The Capacitor Tauri platform brings your web app to the desktop with tiny binaries and a security-first Rust core. Here are some of the key features:

- 🪶 **Tiny binaries**: System-webview apps are a few megabytes instead of the ~100 MB an embedded browser needs.
- 🔒 **Security-first**: A Rust core with deny-by-default permissions; capabilities are generated with the minimum grants your plugins need.
- ⚡ **Familiar workflow**: `cap add`, `cap sync`, `cap run` — the same commands as iOS and Android.
- 🧩 **Curated plugins**: Ready-made implementations of core Capacitor plugins on top of official `tauri-plugin-*` crates.
- 🕸️ **Web plugins run free**: Any Capacitor plugin with a web implementation works via automatic fallback.
- 🔗 **Deep links**: Custom URL schemes delivered through the standard `@capacitor/app` `appUrlOpen` event.
- 📱 **App lifecycle**: `appStateChange`, `pause`, and `resume` events, exactly like on mobile.
- ♻️ **Live reload**: Develop against your web dev server with full HMR.
- 📦 **Packaging**: Native installers (`.dmg`, `.msi`/`.exe`, `.deb`/`.AppImage`) via Tauri's bundler.
- 🧩 **Minimal scaffold**: You own a thin `src-tauri/`; all runtime logic ships in the crate and updates via `cargo update`.
- 🔁 **Up-to-date**: Always supports the latest Capacitor and Tauri versions.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-tauri/issues) and we'll take a look!

## Electron or Tauri?

This platform is a **complement** to the [Capacitor Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/), not a replacement. Pick based on your priorities:

|                | **Tauri** (this platform)                 | **Electron**                                              |
| -------------- | ----------------------------------------- | --------------------------------------------------------- |
| Binary size    | ~3–10 MB                                  | ~80–150 MB                                                |
| Webview        | System (WKWebView / WebView2 / WebKitGTK) | Bundled Chromium                                          |
| Plugin story   | Web impls + curated shims + bespoke Rust  | The full Capacitor plugin ecosystem (any `electron` impl) |
| Web-bundle OTA | Not available                             | Available                                                 |

Choose **Tauri** for lean, secure, kiosk-style and consumer apps. Choose **Electron** for plugin-heavy or OTA-dependent apps.

## Use Cases

The Tauri platform is typically used to bring an existing Capacitor app to the desktop with a minimal footprint, for example:

- **Lean consumer desktop apps**: Ship a few-megabyte installer instead of a hundred-megabyte one.
- **Security-sensitive tools**: Rely on a Rust core with deny-by-default, per-plugin permissions.
- **Kiosk and point-of-sale apps**: Run your web app full screen on dedicated hardware.
- **Internal business tools**: Distribute directly to your team without app stores.

## Compatibility

| Platform Version | Capacitor Version | Tauri Version | Status         |
| ---------------- | ----------------- | ------------- | -------------- |
| 0.x              | >=8.x.x           | >=2.x.x       | Active support |

## Guides

- [Capacitor Tauri Platform: Lean Desktop Apps](https://capawesome.io/blog/announcing-the-capacitor-tauri-platform/)

## Supported Plugins

The plugin story has three tiers (see [Honest Limitations](#honest-limitations)):

| Plugin                                                                                    | Tier         | Backed by                             |
| ----------------------------------------------------------------------------------------- | ------------ | ------------------------------------- |
| [`@capacitor/app`](https://capacitorjs.com/docs/apis/app)                                 | Built-in     | The platform crate + deep-link plugin |
| [`@capacitor/filesystem`](https://capacitorjs.com/docs/apis/filesystem)                   | Curated      | `tauri-plugin-fs`                     |
| [`@capacitor/preferences`](https://capacitorjs.com/docs/apis/preferences)                 | Curated      | `tauri-plugin-store`                  |
| [`@capacitor/dialog`](https://capacitorjs.com/docs/apis/dialog)                           | Curated      | `tauri-plugin-dialog`                 |
| [`@capacitor/local-notifications`](https://capacitorjs.com/docs/apis/local-notifications) | Curated      | `tauri-plugin-notification`           |
| Plugins with a web implementation                                                         | Web fallback | The plugin's own `web` implementation |

Plugins that require native functionality beyond the curated set need a bespoke Rust implementation. Want your favorite plugin curated? Just [open an issue](https://github.com/capawesome-team/capacitor-tauri/issues).

## Prerequisites

Tauri requires the **Rust toolchain** and your platform's system dependencies. Follow the [Tauri prerequisites guide](https://v2.tauri.app/start/prerequisites/) before installing.

## Installation

You can use our **AI-Assisted Setup** to add the platform. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-platforms
```

Then use the following prompt:

```
Use the `capacitor-platforms` skill from `capawesome-team/skills` to add the `@capawesome/capacitor-tauri` platform to my project.
```

If you prefer **Manual Setup**, add the platform by running the following commands:

```
npm install @capawesome/capacitor-tauri
npx cap add @capawesome/capacitor-tauri
```

> [!NOTE] Always use the full package name with Capacitor CLI commands (e.g. `npx cap sync @capawesome/capacitor-tauri`). A bare `npx cap sync tauri` does nothing.

The scaffolded `src-tauri/` project contains only files you own:

| File              | Purpose                                                  |
| ----------------- | -------------------------------------------------------- |
| `src/main.rs`     | ~3 lines: starts the app via the platform crate          |
| `tauri.conf.json` | App configuration (window, CSP, deep links, bundle)      |
| `capabilities/`   | Permission grants (regenerated at sync)                  |
| `Cargo.toml`      | Crate dependencies (curated plugin crates added at sync) |
| `icons/`          | App icons                                                |

Everything with logic lives in the `capacitor-tauri` crate and updates via `cargo update` — your `src-tauri/` never rots.

## Usage

```
# Copy web assets + generate capabilities and plugin registrations
npx cap sync @capawesome/capacitor-tauri

# Run the app (uses server.url for live reload when configured)
npx cap run @capawesome/capacitor-tauri
```

At sync time the platform scans your Capacitor plugin dependencies, generates a deny-by-default capability file with only the permissions the enabled curated plugins need, and wires the matching `tauri-plugin-*` crates into your project.

### Live Reload

Set `server.url` in your Capacitor config to your dev server, then run `npx cap run @capawesome/capacitor-tauri` — it launches `tauri dev` pointing at your dev server with full HMR.

### Deep Links

Declare the scheme in `src-tauri/tauri.conf.json` (`plugins.deep-link.desktop.schemes`) and listen with the standard `@capacitor/app` plugin:

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

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

## Packaging

Sync first, then run Tauri's bundler from your project root:

```
npx cap sync @capawesome/capacitor-tauri
npx tauri build
```

Tauri's bundler produces native installers for the current OS (`.dmg`/`.app`, `.msi`/`.exe`, `.deb`/`.AppImage`). Signing, updater, and target configuration live in `src-tauri/tauri.conf.json` — see the [Tauri distribution guide](https://v2.tauri.app/distribute/).

## Desktop Patterns

Tauri natively supports a few common desktop behaviors. These are recipes you add in your own `src-tauri/`, not platform features — the platform stays out of your way.

### Start Hidden

To launch without flashing an empty window (for tray-style or splash-first apps), mark the main window as hidden in `src-tauri/tauri.conf.json`:

```
{
  "app": {
    "windows": [{ "label": "main", "visible": false }]
  }
}
```

Show it from your frontend once your app is ready, or from a tray menu (see below):

```
import { getCurrentWindow } from '@tauri-apps/api/window';

await getCurrentWindow().show();
```

When the user relaunches the app, the platform automatically unminimizes, shows, and focuses the existing `main` window instead of starting a second instance.

### Tray Icon

Switch your `src-tauri/src/main.rs` from `run` to `builder(...)`, which returns the preconfigured `tauri::Builder` so you can add a `.setup(...)` hook before starting the app:

```
mod generated;

use tauri::{
    menu::{Menu, MenuItem},
    tray::TrayIconBuilder,
    Manager,
};

fn main() {
    capacitor_tauri::builder(generated::register_plugins)
        .setup(|app| {
            let show = MenuItem::with_id(app, "show", "Show", true, None::<&str>)?;
            let hide = MenuItem::with_id(app, "hide", "Hide", true, None::<&str>)?;
            let quit = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
            let menu = Menu::with_items(app, &[&show, &hide, &quit])?;

            TrayIconBuilder::new()
                .icon(app.default_window_icon().expect("window icon is configured in tauri.conf.json").clone())
                .menu(&menu)
                .on_menu_event(|app, event| match event.id.as_ref() {
                    "show" => {
                        if let Some(window) = app.get_webview_window("main") {
                            let _ = window.show();
                            let _ = window.set_focus();
                        }
                    }
                    "hide" => {
                        if let Some(window) = app.get_webview_window("main") {
                            let _ = window.hide();
                        }
                    }
                    "quit" => app.exit(0),
                    _ => {}
                })
                .build(app)?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

The example reuses the app's window icon for the tray, which requires the `icon` entries in `tauri.conf.json` (the scaffold configures them by default).

The tray API needs the `tray-icon` feature on Tauri in `src-tauri/Cargo.toml`:

```
tauri = { version = "2", features = ["tray-icon"] }
```

### Splash Screen

Add a second `splashscreen` window alongside the (hidden) `main` window in `src-tauri/tauri.conf.json`:

```
{
  "app": {
    "windows": [
      { "label": "main", "visible": false },
      { "label": "splashscreen", "url": "splashscreen.html", "width": 400, "height": 300 }
    ]
  }
}
```

Ship a `splashscreen.html` in your web assets, then close the splash and reveal the main window from your frontend once your app has booted:

```
import { getCurrentWindow, Window } from '@tauri-apps/api/window';

await Window.getByLabel('splashscreen').then((splash) => splash?.close());
await getCurrentWindow().show();
```

## Honest Limitations

Read this before choosing Tauri — these are inherent trade-offs, not bugs:

1. **No plugin-ecosystem reuse.** Tauri's core is Rust; there is no Node.js runtime. Only Tier-1 web implementations, the curated Tier-2 shims, and bespoke Tier-3 Rust plugins work. Arbitrary Capacitor native plugins do **not** run. This is the main reason to choose the [Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/) instead.
1. **Three webview engines.** WKWebView (macOS), WebView2 (Windows), and WebKitGTK (Linux) behave differently — a real cross-engine testing burden, worst on Linux. Electron's single bundled Chromium is more predictable.
1. **No web-bundle OTA.** Web assets are compiled into the binary; there is no Live Update / over-the-air web-bundle mechanism. Only full signed binary updates (via `tauri-plugin-updater`) are possible.
1. **Rust toolchain required.** Developers and CI need Rust and platform system dependencies installed, with longer first builds and large `target/` directories.

## FAQ

### Can I use any Capacitor plugin?

Only plugins with a web implementation, a curated Tier-2 shim, or a bespoke Tauri implementation (see [Supported Plugins](#supported-plugins)). If you need the full plugin ecosystem, use the [Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/).

### Does `Capacitor.getPlatform()` return `tauri`?

Yes. `Capacitor.getPlatform()` returns `'tauri'` and `Capacitor.isNativePlatform()` returns `true`.

### Does this support over-the-air updates?

Not for web bundles. Tauri compiles the web assets into the binary; only full signed binary updates are supported.

## Related

- [Capacitor Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/) — maximum compatibility and web-bundle OTA, with larger binaries.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-tauri/blob/main/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-tauri/blob/main/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by the Tauri Programme within the Commons Conservancy. `Tauri` is a trademark of the Tauri Programme within the Commons Conservancy. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Text Interaction Plugin

Capacitor plugin to enable and disable text interaction (selection, magnifier, callout menu) in the app's WebView.

## Features

- ✋ **Text interaction**: Enable and disable text interaction at runtime.
- 🔍 **State**: Read whether text interaction is currently enabled.
- 🧩 **Zero-config**: No changes to your native project required.
- 🤝 **Compatibility**: Works alongside the [Clipboard](https://capawesome.io/docs/sdks/capacitor/clipboard/), [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/) and [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Text Interaction plugin is typically used to make web content feel like a native app, for example:

- **App-like UIs**: Disable text selection, the magnifier and the callout menu so buttons, menus and other controls don't trigger accidental text selection.
- **Kiosk apps**: Prevent users from selecting and copying content in apps running on public or shared devices.
- **Reading views**: Re-enable text interaction at runtime in views where users should be able to select and copy text.
- **Settings toggles**: Read the current state with `isEnabled()` to keep an in-app toggle in sync.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-text-interaction` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-text-interaction
npx cap sync
```

This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented. On Web, use the CSS `user-select` property to prevent text selection instead.

### iOS

No additional setup is required.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to disable text interaction, enable it again, and check whether it is currently enabled.

### Disable text interaction

Turn off the system text-interaction gestures, that is text selection, the selection magnifier and the callout (copy/paste) menu. Only available on iOS:

```
import { TextInteraction } from '@capawesome/capacitor-text-interaction';

const disable = async () => {
  await TextInteraction.disable();
};
```

### Enable text interaction

Re-enable text interaction after it has been disabled. Text interaction is enabled by default. Only available on iOS:

```
import { TextInteraction } from '@capawesome/capacitor-text-interaction';

const enable = async () => {
  await TextInteraction.enable();
};
```

### Check whether text interaction is enabled

Read the current state, for example to keep a settings toggle in sync. Only available on iOS:

```
import { TextInteraction } from '@capawesome/capacitor-text-interaction';

const isEnabled = async () => {
  const { enabled } = await TextInteraction.isEnabled();
  return enabled;
};
```

## API

- [`disable()`](#disable)
- [`enable()`](#enable)
- [`isEnabled()`](#isenabled)
- [Interfaces](#interfaces)

### disable()

```
disable() => Promise<void>
```

Disable text interaction in the app's WebView.

This turns off system text-interaction gestures such as text selection, the selection magnifier and the callout (copy/paste) menu.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### enable()

```
enable() => Promise<void>
```

Enable text interaction in the app's WebView.

Text interaction is enabled by default.

Only available on iOS.

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Check whether text interaction is currently enabled in the app's WebView.

Only available on iOS.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IsEnabledResult

| Prop          | Type      | Description                                    | Since |
| ------------- | --------- | ---------------------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether text interaction is currently enabled. | 0.1.0 |

## Text Interaction Behavior

Text interaction covers the system gestures that let a user work with text in the WebView: text selection, the selection magnifier and the callout (copy/paste) menu.

- **Beyond CSS**: The CSS `user-select: none` property prevents text selection for specific elements and covers most cases. This plugin disables the system text-interaction gestures as a whole, which is useful for app-like UIs where accidental text selection breaks the experience.
- **Default state**: Text interaction is enabled by default.
- **Runtime toggling**: Changes apply to the WebView's configuration. If a change does not take effect immediately on already-rendered content, reload the WebView content to apply it.

## FAQ

### How is this plugin different from other similar plugins?

It disables the system text-interaction gestures — text selection, the selection magnifier, and the callout (copy/paste) menu — as a whole at runtime, which is exactly what app-like UIs need when accidental selection breaks the experience. It requires no native setup, exposes a fully typed API with a state check so you can keep an in-app toggle in sync, and ships for both CocoaPods and Swift Package Manager. If the CSS `user-select: none` property on specific elements covers your case, that is perfectly fine; if you want to control the WebView's text gestures as a whole, this plugin is built for it.

### Why is this plugin only available on iOS?

The plugin controls the system text-interaction gestures of the iOS WebView. On Android and Web, all methods reject as unimplemented. On Web, you can use the CSS `user-select` property to prevent text selection instead.

### What is the difference between this plugin and the CSS `user-select` property?

The CSS `user-select: none` property prevents text selection for specific elements and covers most cases. This plugin disables the system text-interaction gestures as a whole, including text selection, the selection magnifier and the callout (copy/paste) menu, which is useful for app-like UIs where accidental text selection breaks the experience. See [Text Interaction Behavior](#text-interaction-behavior) for more details.

### Is text interaction enabled by default?

Yes, text interaction is enabled by default. Call `disable()` to turn it off and `enable()` to restore the default behavior. You can read the current state at any time with `isEnabled()`.

### Why does a change not take effect immediately?

Changes apply to the WebView's configuration. If a change does not take effect immediately on already-rendered content, reload the WebView content to apply it.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Clipboard](https://capawesome.io/docs/sdks/capacitor/clipboard/): Read from and write to the system clipboard.
- [Privacy Screen](https://capawesome.io/docs/sdks/capacitor/privacy-screen/): Hide sensitive app content in the app switcher and block screenshots.
- [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/): Detect an outdated Android System WebView and guide users to update it.
- [Text Zoom](https://capawesome.io/docs/sdks/capacitor/text-zoom/): Read and control the WebView text zoom.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/text-interaction/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/text-interaction/LICENSE).

# Capacitor Text Zoom Plugin

Capacitor plugin for reading and controlling the WebView text zoom.

## Features

- 🔍 **Read zoom**: Read the current text zoom of the WebView.
- 🔠 **Set zoom**: Set the text zoom, e.g. to offer your own text-size setting.
- ♿ **Preferred zoom**: Read the device's preferred text zoom to respect the operating system's font size settings.
- 🤝 **Compatibility**: Works alongside the [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/) plugin, whose font scale is a natural input for the text zoom.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Text Zoom plugin is typically used to make the text size of an app adjustable, for example:

- **Custom text-size settings**: Offer an in-app setting that lets users increase or decrease the text size with `setZoom(...)`.
- **Accessibility**: Read the device's preferred text zoom with `getPreferredZoom()` and apply it to respect the operating system's font size settings.
- **Reading-focused apps**: Let users of news, book, or documentation apps adjust the text size to their comfort.
- **Restoring the zoom on app launch**: Read the persisted value from a preferences plugin and re-apply it with `setZoom(...)` on startup.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-text-zoom` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands:

```
npm install @capawesome/capacitor-text-zoom
npx cap sync
```

This plugin is available on **Android** and **iOS**. On Web, all methods reject as unimplemented.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to read the current text zoom, read the device's preferred text zoom, and set the text zoom of the WebView.

### Read the current text zoom

Get the current text zoom of the WebView, where `1.0` equals `100%` (no zoom). Only available on Android and iOS:

```
import { TextZoom } from '@capawesome/capacitor-text-zoom';

const getZoom = async () => {
  const { zoom } = await TextZoom.getZoom();
  return zoom;
};
```

### Read the preferred text zoom of the device

Get the preferred text zoom based on the operating system's font size settings, for example to use it as an input for `setZoom(...)`. Only available on Android and iOS:

```
import { TextZoom } from '@capawesome/capacitor-text-zoom';

const getPreferredZoom = async () => {
  const { zoom } = await TextZoom.getPreferredZoom();
  return zoom;
};
```

### Set the text zoom

Set the text zoom of the WebView. The value must be greater than `0` and is not persisted across app restarts. Only available on Android and iOS:

```
import { TextZoom } from '@capawesome/capacitor-text-zoom';

const setZoom = async () => {
  await TextZoom.setZoom({ zoom: 1.5 });
};
```

## Migration from `@capacitor/text-zoom`

This plugin is a drop-in alternative to the official [`@capacitor/text-zoom`](https://www.npmjs.com/package/@capacitor/text-zoom) plugin with a slightly more explicit API:

| `@capacitor/text-zoom`         | `@capawesome/capacitor-text-zoom` |
| ------------------------------ | --------------------------------- |
| `get()` → `{ value }`          | `getZoom()` → `{ zoom }`          |
| `getPreferred()` → `{ value }` | `getPreferredZoom()` → `{ zoom }` |
| `set({ value })`               | `setZoom({ zoom })`               |

## API

- [`getPreferredZoom()`](#getpreferredzoom)
- [`getZoom()`](#getzoom)
- [`setZoom(...)`](#setzoom)
- [Interfaces](#interfaces)

### getPreferredZoom()

```
getPreferredZoom() => Promise<GetPreferredZoomResult>
```

Get the preferred text zoom of the device based on the operating system's font size settings.

This value can be used as an input for `setZoom(...)` to respect the user's system font size preference.

Only available on Android and iOS.

**Returns:** `Promise<GetPreferredZoomResult>`

**Since:** 0.1.0

______________________________________________________________________

### getZoom()

```
getZoom() => Promise<GetZoomResult>
```

Get the current text zoom of the WebView.

Only available on Android and iOS.

**Returns:** `Promise<GetZoomResult>`

**Since:** 0.1.0

______________________________________________________________________

### setZoom(...)

```
setZoom(options: SetZoomOptions) => Promise<void>
```

Set the text zoom of the WebView.

The zoom is not persisted across app restarts. Persist the value with a preferences plugin and re-apply it on app launch if needed.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `SetZoomOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetPreferredZoomResult

| Prop       | Type     | Description                                                  | Since |
| ---------- | -------- | ------------------------------------------------------------ | ----- |
| **`zoom`** | `number` | The preferred text zoom where `1.0` equals `100%` (no zoom). | 0.1.0 |

#### GetZoomResult

| Prop       | Type     | Description                                                | Since |
| ---------- | -------- | ---------------------------------------------------------- | ----- |
| **`zoom`** | `number` | The current text zoom where `1.0` equals `100%` (no zoom). | 0.1.0 |

#### SetZoomOptions

| Prop       | Type     | Description                                                                         | Since |
| ---------- | -------- | ----------------------------------------------------------------------------------- | ----- |
| **`zoom`** | `number` | The text zoom to set where `1.0` equals `100%` (no zoom). Must be greater than `0`. | 0.1.0 |

## Platform Notes

### iOS

The text zoom is implemented via the `-webkit-text-size-adjust` CSS property, which only takes effect when the WebView runs in **mobile content mode**. On iPad, the WebView defaults to desktop content mode, so `setZoom(...)` has no visible effect unless you set the following in your `capacitor.config`:

```
{
  "ios": {
    "preferredContentMode": "mobile"
  }
}
```

### Persistence

The text zoom is **not** persisted across app restarts. Persist the value with a preferences plugin (e.g. [`@capacitor/preferences`](https://www.npmjs.com/package/@capacitor/preferences)) and re-apply it on app launch if needed.

## FAQ

### How is this plugin different from other similar plugins?

It lets you read and set the WebView text zoom on Android and iOS, and it can also read the device's preferred zoom so your app can respect the operating system's font size settings for better accessibility. The API is explicit and fully typed, supports both CocoaPods and Swift Package Manager on iOS, and is actively maintained against the latest Capacitor and OS versions, with clear platform notes for cases like iPad content mode. If you only need a fixed text size, you may not need it at all; if you want an adjustable, accessibility-aware text size, it is built for exactly that.

### How is this plugin different from the official `@capacitor/text-zoom` plugin?

This plugin is a drop-in alternative to the official `@capacitor/text-zoom` plugin with a slightly more explicit API: `get()` becomes `getZoom()`, `getPreferred()` becomes `getPreferredZoom()`, and `set({ value })` becomes `setZoom({ zoom })`. See the [migration table](#migration-from-capacitortext-zoom) above for a side-by-side comparison.

### Why does `setZoom` have no effect on iPad?

On iOS, the text zoom is implemented via the `-webkit-text-size-adjust` CSS property, which only takes effect when the WebView runs in mobile content mode. On iPad, the WebView defaults to desktop content mode, so you need to set `preferredContentMode` to `mobile` in the `ios` section of your `capacitor.config` (see [Platform Notes](#platform-notes)).

### Is the text zoom persisted across app restarts?

No, the text zoom is not persisted. Persist the value with a preferences plugin such as `@capacitor/preferences` and re-apply it with `setZoom(...)` on app launch if needed.

### How do I respect the user's system font size?

Call `getPreferredZoom()` to read the preferred text zoom of the device based on the operating system's font size settings, and pass the returned value to `setZoom(...)`. This way, the text size of your app follows the user's system preference.

### Which platforms are supported?

The plugin is available on Android and iOS. On Web, all methods reject as unimplemented.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Accessibility Preferences](https://capawesome.io/docs/sdks/capacitor/accessibility-preferences/): Read the user's system accessibility preferences, such as the font scale.
- [Screen Reader](https://capawesome.io/docs/sdks/capacitor/screen-reader/): Interact with screen readers.
- [Text Interaction](https://capawesome.io/docs/sdks/capacitor/text-interaction/): Enable and disable text interaction (selection, magnifier, callout menu) in the app's WebView.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/text-zoom/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/text-zoom/LICENSE).

# Capacitor Thermal State Plugin

Capacitor plugin to read the device thermal state and react before the operating system throttles your app.

## Features

- 🌡️ **Thermal state**: Read the current thermal state of the device.
- 🔔 **Change events**: Get notified whenever the thermal state changes.
- 🤝 **Compatibility**: Works alongside the [Battery](https://capawesome.io/docs/sdks/capacitor/battery/) and [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Thermal State plugin is typically used to adapt an app's workload to the device's thermal condition, for example:

- **Video and streaming apps**: Lower the video quality or frame rate when the thermal state becomes serious.
- **Games and 3D rendering**: Reduce graphical effects to help the device cool down before the operating system throttles the app.
- **Machine learning**: Defer on-device ML inference or other background work while the thermal state is elevated.
- **Data prefetching**: Reduce the prefetching rate or pause background sync when the device gets warm.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How to gate heavy work like video processing or ML inference before the OS throttles your app.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-thermal-state` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-thermal-state
npx cap sync
```

This plugin is available on **Android** and **iOS**. On the web, all methods reject as unimplemented.

### Android

Reading the thermal state requires **Android 10** (API level 29) or newer. On older versions, `getThermalState(...)` rejects as unavailable and the `thermalStateChange` event is never emitted.

The Android thermal status values are mapped to the four common thermal states as follows:

| Android Thermal Status                                                                                       | Thermal State |
| ------------------------------------------------------------------------------------------------------------ | ------------- |
| `THERMAL_STATUS_NONE`                                                                                        | `nominal`     |
| `THERMAL_STATUS_LIGHT`                                                                                       | `fair`        |
| `THERMAL_STATUS_MODERATE`                                                                                    | `serious`     |
| `THERMAL_STATUS_SEVERE` / `THERMAL_STATUS_CRITICAL` / `THERMAL_STATUS_EMERGENCY` / `THERMAL_STATUS_SHUTDOWN` | `critical`    |

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get the current thermal state, listen for thermal state changes, and remove all listeners.

### Get the current thermal state

Read the current thermal state of the device, for example to decide how much work your app should perform. Only available on Android (API level 29+) and iOS:

```
import { ThermalState } from '@capawesome/capacitor-thermal-state';

const getThermalState = async () => {
  const { state } = await ThermalState.getThermalState();
  return state;
};
```

### Listen for thermal state changes

Get notified whenever the thermal state of the device changes. The device is only observed while at least one listener is attached. Only available on Android (API level 29+) and iOS:

```
import { ThermalState } from '@capawesome/capacitor-thermal-state';

const addThermalStateChangeListener = async () => {
  await ThermalState.addListener('thermalStateChange', event => {
    console.log(event.state);
  });
};
```

### Remove all listeners

Remove all listeners for this plugin when you no longer need to observe the thermal state:

```
import { ThermalState } from '@capawesome/capacitor-thermal-state';

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

## API

- [`getThermalState()`](#getthermalstate)
- [`addListener('thermalStateChange', ...)`](#addlistenerthermalstatechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getThermalState()

```
getThermalState() => Promise<GetThermalStateResult>
```

Get the current thermal state of the device.

Only available on Android (API level 29+) and iOS.

**Returns:** `Promise<GetThermalStateResult>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('thermalStateChange', ...)

```
addListener(eventName: 'thermalStateChange', listenerFunc: (event: ThermalStateChangeEvent) => void) => Promise<PluginListenerHandle>
```

Listen for changes to the thermal state of the device.

The device is only observed while at least one listener is attached.

Only available on Android (API level 29+) and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'thermalStateChange'`                     |
| **`listenerFunc`** | `(event: ThermalStateChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetThermalStateResult

| Prop        | Type                | Description                              | Since |
| ----------- | ------------------- | ---------------------------------------- | ----- |
| **`state`** | `ThermalStateValue` | The current thermal state of the device. | 0.1.0 |

#### PluginListenerHandle

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

#### ThermalStateChangeEvent

| Prop        | Type                | Description                              | Since |
| ----------- | ------------------- | ---------------------------------------- | ----- |
| **`state`** | `ThermalStateValue` | The current thermal state of the device. | 0.1.0 |

### Type Aliases

#### ThermalStateValue

The thermal state of the device.

- `critical`: The thermal state is significantly impacting performance. Reduce the workload as much as possible.
- `fair`: The thermal state is slightly elevated. Consider reducing non-essential work.
- `nominal`: The thermal state is within normal limits. No action is needed.
- `serious`: The thermal state is high. Reduce the workload to help the device cool down.

`'critical' | 'fair' | 'nominal' | 'serious'`

## Handling the Thermal State

Use the thermal state to progressively reduce your app's workload before the operating system throttles it. The following table lists suggested reactions for each state:

| State      | Suggested App Reaction                                                     |
| ---------- | -------------------------------------------------------------------------- |
| `nominal`  | No action needed. Run at full quality.                                     |
| `fair`     | Reduce non-essential work, e.g. lower the prefetching rate.                |
| `serious`  | Reduce the frame rate, pause prefetching, and defer background or ML work. |
| `critical` | Reduce the workload as much as possible to help the device cool down.      |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. On Android, reading the thermal state requires Android 10 (API level 29) or newer. On the web, all methods reject as unimplemented.

### Why does `getThermalState` reject on my Android device?

Reading the thermal state requires Android 10 (API level 29) or newer. On older Android versions, `getThermalState(...)` rejects as unavailable and the `thermalStateChange` event is never emitted.

### What do the different thermal states mean?

The plugin reports one of four states: `nominal` means the thermal state is within normal limits, `fair` means it is slightly elevated, `serious` means it is high and the workload should be reduced, and `critical` means performance is significantly impacted and the workload should be reduced as much as possible. See [Handling the Thermal State](#handling-the-thermal-state) for suggested reactions to each state.

### Why is the `thermalStateChange` event not emitted?

The device is only observed while at least one listener is attached, so make sure you have added a listener for the `thermalStateChange` event. Also note that the event is never emitted on Android versions older than Android 10 (API level 29).

### Do I need any permissions or configuration to use this plugin?

No, the plugin does not require any permissions or configuration. Simply [install](#installation) it and call its methods.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Battery](https://capawesome.io/docs/sdks/capacitor/battery/): Access battery information of the device.
- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information such as the model, manufacturer, operating system, and memory.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/thermal-state/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/thermal-state/LICENSE).

# Capacitor TikTok App Events Plugin

Unofficial Capacitor plugin for the [TikTok App Events SDK](https://ads.tiktok.com/help/article/how-to-integrate-tiktok-app-events-sdk).[1](#fn:1)

## Features

The Capacitor TikTok App Events plugin is a modern integration of the TikTok App Events SDK for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📊 **Event Tracking**: Track standard and custom events with properties such as currency, value and contents.
- 🤖 **Automatic Events**: Let the SDK log app installs, launches, retention and in-app purchases automatically.
- 👤 **Identification**: Improve attribution by identifying users with hashed personal data.
- 🐞 **Debug Mode**: Verify your integration in the TikTok Events Manager before you release.
- 🍎 **SKAdNetwork**: Control whether the SDK updates the SKAdNetwork conversion value on iOS.
- 🔒 **Limited Data Use**: Enable Limited Data Use mode to comply with privacy regulations.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The TikTok App Events plugin is typically used to measure and optimize TikTok ad campaigns, for example:

- **App install campaigns**: Attribute app installs to your TikTok ads.
- **Conversion tracking**: Report purchases, registrations and other in-app conversions to TikTok.
- **App event optimization**: Optimize your campaigns for the in-app events that matter to your business.
- **Retargeting**: Build custom audiences from in-app activity to re-engage existing users.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-tiktok-app-events` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-tiktok-app-events
npx cap sync
```

This plugin requires a [TikTok for Business](https://ads.tiktok.com/) account. Connect your app in the **TikTok Events Manager** and generate a **TikTok App ID** and an **Access Token** as described in the [TikTok guide](https://ads.tiktok.com/help/article/how-to-integrate-tiktok-app-events-sdk).

> [!IMPORTANT] Use of the TikTok App Events SDK is governed by the [TikTok for Business Commercial Terms of Service](https://ads.tiktok.com/i18n/official/policy/commercial-terms-of-service) and the [TikTok Business Products (Data) Terms](https://ads.tiktok.com/i18n/official/policy/business-products-terms), which prohibit sharing sensitive data with TikTok (see [Third-Party Notices](#third-party-notices)). This plugin declares the SDKs as dependencies and downloads them from JitPack, CocoaPods or Swift Package Manager at build time. It does not bundle or modify them.

### Android

The [TikTok App Events SDK for Android](https://github.com/tiktok/tiktok-business-android-sdk) is resolved from [JitPack](https://jitpack.io/). The plugin already declares the JitPack repository in its `build.gradle` file. If your project restricts repository declarations to the settings file (e.g. via `dependencyResolutionManagement` with `FAIL_ON_PROJECT_REPOS`), add the JitPack repository to your `settings.gradle` file:

```
dependencyResolutionManagement {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}
```

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$tiktokBusinessSdkVersion` version of `com.github.tiktok:tiktok-business-android-sdk` (default: `1.7.1`)
- `$installReferrerVersion` version of `com.android.installreferrer:installreferrer` (default: `2.2`)

### iOS

The [TikTok App Events SDK for iOS](https://github.com/tiktok/tiktok-business-ios-sdk) can be integrated via Swift Package Manager (recommended) or CocoaPods.

#### App Tracking Transparency

The SDK only collects the advertising identifier (IDFA) if the user has granted tracking permission. You can request the permission with the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugin.

#### SKAdNetwork

To attribute installs via SKAdNetwork, add the TikTok SKAdNetwork identifiers to your `ios/App/App/Info.plist` file as described in the [TikTok App Events SDK documentation](https://business-api.tiktok.com/portal/docs?id=1739585432134657). If another SDK (e.g. a mobile measurement partner) already updates the SKAdNetwork conversion value, set `iosSkAdNetworkSupport` to `false` when calling `initialize(...)`.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Initialize the plugin

Call `initialize(...)` once before all other methods, for example on app start or after the user has given consent:

```
import { TiktokAppEvents } from '@capawesome/capacitor-tiktok-app-events';

const initialize = async () => {
  await TiktokAppEvents.initialize({
    accessToken: 'YOUR_ACCESS_TOKEN',
    tiktokAppId: 'YOUR_TIKTOK_APP_ID',
    iosAppId: 'YOUR_APP_STORE_ID',
  });
};
```

### Track events

Track a standard event with properties or a custom event:

```
import { TiktokAppEvents } from '@capawesome/capacitor-tiktok-app-events';

const trackPurchase = async () => {
  await TiktokAppEvents.trackEvent({
    name: 'Purchase',
    properties: {
      currency: 'USD',
      value: 9.99,
      contents: [
        {
          content_id: 'sku-123',
          content_type: 'product',
          quantity: 1,
          price: 9.99,
        },
      ],
    },
  });
};

const trackCustomEvent = async () => {
  await TiktokAppEvents.trackEvent({
    name: 'LevelCompleted',
    properties: { level: 3 },
  });
};
```

See [Supported In-App Events](https://ads.tiktok.com/help/article/all-supported-in-app-events) for the list of standard event names and properties.

### Identify the user

Identify the user after sign-in and log out when the user signs out:

```
import { TiktokAppEvents } from '@capawesome/capacitor-tiktok-app-events';

const identify = async () => {
  await TiktokAppEvents.identify({
    externalId: 'user-123',
    email: 'jane.doe@example.com',
  });
};

const logout = async () => {
  await TiktokAppEvents.logout();
};
```

## API

- [`flush()`](#flush)
- [`identify(...)`](#identify)
- [`initialize(...)`](#initialize)
- [`logout()`](#logout)
- [`trackEvent(...)`](#trackevent)
- [Interfaces](#interfaces)

### flush()

```
flush() => Promise<void>
```

Flush all queued events to TikTok immediately.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### identify(...)

```
identify(options: IdentifyOptions) => Promise<void>
```

Identify the current user to improve the attribution of events.

Personal data is hashed (SHA-256) by the TikTok SDK on the device before it is sent to TikTok.

Only available on Android and iOS.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `IdentifyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize the TikTok App Events SDK.

This method must be called before any other method.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### logout()

```
logout() => Promise<void>
```

Log out the current user and clear the identification data.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### trackEvent(...)

```
trackEvent(options: TrackEventOptions) => Promise<void>
```

Track an event.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `TrackEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### IdentifyOptions

| Prop                   | Type     | Description                                       | Since |
| ---------------------- | -------- | ------------------------------------------------- | ----- |
| **`email`**            | `string` | The email address of the user.                    | 0.1.0 |
| **`externalId`**       | `string` | The unique identifier of the user in your system. | 0.1.0 |
| **`externalUserName`** | `string` | The user name of the user.                        | 0.1.0 |
| **`phoneNumber`**      | `string` | The phone number of the user.                     | 0.1.0 |

#### InitializeOptions

| Prop                            | Type      | Description                                                                                                                                                                                                       | Default | Since |
| ------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`accessToken`**               | `string`  | The access token of your app. You can find it in the TikTok Events Manager.                                                                                                                                       |         | 0.1.0 |
| **`automaticPurchaseTracking`** | `boolean` | Whether the SDK automatically tracks in-app purchases made through Google Play Billing (Android) or StoreKit (iOS).                                                                                               | `true`  | 0.1.0 |
| **`automaticTracking`**         | `boolean` | Whether the SDK automatically tracks app installs, app launches and second-day retention.                                                                                                                         | `true`  | 0.1.0 |
| **`debugMode`**                 | `boolean` | Whether debug mode is enabled. In debug mode, events are sent to the test events pipeline of the TikTok Events Manager and are not used for reporting. Make sure to disable debug mode before releasing your app. | `false` | 0.1.0 |
| **`iosAppId`**                  | `string`  | The App Store ID of your app. Required on iOS. On Android, the package name of your app is used instead. Only available on iOS.                                                                                   |         | 0.1.0 |
| **`iosSkAdNetworkSupport`**     | `boolean` | Whether the SDK updates the SKAdNetwork conversion value. Disable this if another SDK (e.g. a mobile measurement partner) already updates the conversion value to avoid conflicts. Only available on iOS.         | `true`  | 0.1.0 |
| **`limitedDataUse`**            | `boolean` | Whether Limited Data Use (LDU) mode is enabled.                                                                                                                                                                   | `false` | 0.1.0 |
| **`tiktokAppId`**               | `string`  | The TikTok App ID of your app. You can find it in the TikTok Events Manager. Multiple IDs can be provided as a comma-separated list.                                                                              |         | 0.1.0 |

#### TrackEventOptions

| Prop             | Type                      | Description                                                                                                                | Since |
| ---------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**         | `string`                  | A unique identifier of the event. Used by TikTok to deduplicate events that are also reported through the Events API.      | 0.1.0 |
| **`name`**       | `string`                  | The name of the event. Can be a standard event name (e.g. `Purchase`, `AddToCart`, `Registration`) or a custom event name. | 0.1.0 |
| **`properties`** | `Record<string, unknown>` | The properties of the event.                                                                                               | 0.1.0 |

## FAQ

### Do I need a TikTok for Business account to use this plugin?

Yes. This plugin wraps the official TikTok App Events SDKs, which require a [TikTok for Business](https://ads.tiktok.com/) account, a TikTok App ID and an access token.

### Where do I find the TikTok App ID and the access token?

Both are generated in the TikTok Events Manager when you connect your app with the TikTok SDK. See the [TikTok guide](https://ads.tiktok.com/help/article/how-to-integrate-tiktok-app-events-sdk) for step-by-step instructions.

### How can I verify that events are received by TikTok?

Enable `debugMode` when calling `initialize(...)`. Events are then sent to the test events pipeline and appear in the **Test Events** tab of the TikTok Events Manager. Call `flush()` to send queued events immediately. Make sure to disable debug mode before releasing your app.

### Is personal data hashed before it is sent to TikTok?

Yes. The TikTok SDK hashes the email address, phone number and external ID with SHA-256 on the device before they are sent to TikTok.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the tracking permission required to collect the IDFA on iOS.
- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Unofficial Capacitor plugin for Firebase Analytics.
- [PostHog](https://capawesome.io/docs/sdks/capacitor/posthog/): Unofficial Capacitor plugin for the PostHog product analytics platform.
- [Singular](https://capawesome.io/docs/sdks/capacitor/singular/): Unofficial Capacitor plugin for the Singular Mobile SDK.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/tiktok-app-events/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/tiktok-app-events/LICENSE).

## Third-Party Notices

The TikTok App Events SDKs for Android and iOS are licensed under the MIT license and are distributed via JitPack, CocoaPods, and Swift Package Manager. Their use is additionally governed by the [TikTok for Business Commercial Terms of Service](https://ads.tiktok.com/i18n/official/policy/commercial-terms-of-service) and the [TikTok Business Products (Data) Terms](https://ads.tiktok.com/i18n/official/policy/business-products-terms), which include the obligation not to share sensitive data with TikTok. This plugin only declares these SDKs as dependencies and does not bundle or modify them. The MIT license of this plugin covers the wrapper code only, not the TikTok SDKs.

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by TikTok Inc. or any of its affiliates or subsidiaries. "TikTok" is a trademark of TikTok Inc. or its affiliates. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Toast Plugin

Capacitor plugin to show native toast notifications.

## Features

- 🍞 **Native toasts**: Show short, non-blocking text notifications on Android and iOS.
- 🌐 **Zero-dependency web**: A self-contained web implementation with no additional peer dependencies.
- 🧭 **Positioning**: Show toasts at the top, center or bottom of the screen.
- ⏱️ **Durations**: Choose between a short and a long display duration.
- 🤝 **Compatibility**: Works alongside the [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/), [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/) and [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Toast plugin is typically used to give users brief, non-blocking feedback, for example:

- **Success confirmations**: Confirm that an action such as saving or sending was completed.
- **Error notices**: Inform users about a failed action without interrupting their flow.
- **Clipboard feedback**: Confirm that a value was copied to the clipboard.
- **Status updates**: Show short status messages such as a lost network connection.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-toast` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-toast
npx cap sync
```

### Android

No additional configuration is required for this plugin.

On Android 12 and newer, the operating system ignores the requested position and always shows toasts at the bottom of the screen. This is a system restriction and not a bug of this plugin.

### iOS

No additional configuration is required for this plugin.

## Configuration

No configuration required for this plugin.

## Usage

The following example shows how to show a toast.

### Show a toast

Show a short, non-blocking text notification. Use the `duration` option to choose between a short (about 2000 ms) and a long (about 3500 ms) display duration, and the `position` option to show the toast at the top, center or bottom of the screen:

```
import { Toast, ToastDuration, ToastPosition } from '@capawesome/capacitor-toast';

const show = async () => {
  await Toast.show({
    text: 'Hello World!',
    duration: ToastDuration.Short,
    position: ToastPosition.Bottom,
  });
};
```

## API

- [`show(...)`](#show)
- [Interfaces](#interfaces)
- [Enums](#enums)

### show(...)

```
show(options: ShowOptions) => Promise<void>
```

Show a toast with a short text message.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ShowOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ShowOptions

| Prop           | Type            | Description                                                                                                                                                                 | Default                | Since |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
| **`duration`** | `ToastDuration` | The duration of the toast.                                                                                                                                                  | `ToastDuration.Short`  | 0.1.0 |
| **`position`** | `ToastPosition` | The position of the toast on the screen. On Android 12 and newer, the position is ignored and the toast is always shown at the bottom of the screen (a system restriction). | `ToastPosition.Bottom` | 0.1.0 |
| **`text`**     | `string`        | The text to show in the toast.                                                                                                                                              |                        | 0.1.0 |

### Enums

#### ToastDuration

| Members     | Value     | Description                                                  | Since |
| ----------- | --------- | ------------------------------------------------------------ | ----- |
| **`Long`**  | `'LONG'`  | Show the toast for a longer period of time (about 3500 ms).  | 0.1.0 |
| **`Short`** | `'SHORT'` | Show the toast for a shorter period of time (about 2000 ms). | 0.1.0 |

#### ToastPosition

| Members      | Value      | Description                                 | Since |
| ------------ | ---------- | ------------------------------------------- | ----- |
| **`Bottom`** | `'BOTTOM'` | Show the toast at the bottom of the screen. | 0.1.0 |
| **`Center`** | `'CENTER'` | Show the toast in the center of the screen. | 0.1.0 |
| **`Top`**    | `'TOP'`    | Show the toast at the top of the screen.    | 0.1.0 |

## Migrating from `@capacitor/toast`

This plugin offers an API very similar to the official [`@capacitor/toast`](https://github.com/ionic-team/capacitor-plugins/tree/main/toast) plugin, so migrating is straightforward:

- Replace the dependency `@capacitor/toast` with `@capawesome/capacitor-toast`.
- The web implementation is self-contained, so the [`@ionic/pwa-elements`](https://github.com/ionic-team/pwa-elements) package is no longer required for toasts.
- The `duration` and `position` options are now typed enums with uppercase string values (e.g. `ToastDuration.Short` → `'SHORT'`, `ToastPosition.Bottom` → `'BOTTOM'`) instead of lowercase string literals.

## FAQ

### How is this plugin different from other similar plugins?

It shows native toast notifications on Android and iOS and ships a self-contained web implementation with no additional peer dependencies, so toasts work out of the box on every platform. You get typed enums for choosing a short or long duration and a top, center, or bottom position, all through a fully typed API that supports both CocoaPods and Swift Package Manager on iOS and is actively maintained against the latest Capacitor version. If you just need brief, non-blocking feedback anywhere your app runs, a single dependency covers the whole story.

### Why is my toast always shown at the bottom of the screen on Android?

On Android 12 and newer, the operating system ignores the requested position and always shows toasts at the bottom of the screen. This is a system restriction and not a bug of this plugin.

### How long is a toast displayed?

You can choose between two durations with the `duration` option: `ToastDuration.Short` shows the toast for about 2000 ms and `ToastDuration.Long` for about 3500 ms. If you don't set the option, the short duration is used by default.

### How is this plugin different from the official `@capacitor/toast` plugin?

The API is very similar, so migrating is straightforward. The main differences are that the web implementation is self-contained (so the `@ionic/pwa-elements` package is no longer required for toasts) and that the `duration` and `position` options are typed enums with uppercase string values. See [Migrating from `@capacitor/toast`](#migrating-from-capacitortoast) for details.

### Do I need to install `@ionic/pwa-elements` for the web?

No, the plugin ships with a self-contained web implementation that has no additional peer dependencies. Toasts work on the web out of the box after [installing](#installation) the plugin.

### Do I need any permissions or configuration to use this plugin?

No, the plugin does not require any permissions or configuration on Android, iOS, or Web. Simply [install](#installation) it and call the `show(...)` method.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/): Show native action sheets.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon.
- [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/): Show native alert, confirm, and prompt dialogs.
- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/): Provide haptic feedback such as impacts, notifications, and vibrations.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/toast/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/toast/LICENSE).

# Capacitor Torch Plugin

Capacitor plugin for switching the flashlight on and off.

## Features

The Capacitor Torch plugin is one of the most complete flashlight control solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🔦 **Torch control**: Enable, disable, and toggle torch/flashlight.
- ✅ **Availability check**: Check if torch is available on the device.
- 🌐 **Web support**: Uses MediaStream API for web torch control.
- 🤝 **Compatibility**: Works alongside the [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/) and [Light Sensor](https://capawesome.io/docs/sdks/capacitor/light-sensor/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Torch plugin is typically used whenever an app needs to control the device's flashlight, for example:

- **Flashlight features**: Turn the flashlight on and off with a single tap in your app.
- **Barcode and QR code scanning**: Let users enable the torch to scan codes in low-light environments.
- **Document capture**: Improve capture quality in dark surroundings by enabling the torch.
- **Signaling**: Toggle the torch to draw attention, for example as an emergency signal light.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Demo

A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-torch` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-torch
npx cap sync
```

### Android

#### Permissions

This API requires the following permissions be added to your `AndroidManifest.xml` before the `application` tag:

```
<!-- To get access to the flashlight. -->
<uses-permission android:name="android.permission.FLASHLIGHT"/>
```

#### 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:

- `$androidxCameraCoreVersion` version of `androidx.camera:camera-core` (default: `1.5.2`)

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

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check if the torch is available, turn the torch on and off, toggle the torch, and check if the torch is enabled.

### Check if the torch is available

Not every device has a torch, so check the availability before showing a flashlight control in your UI:

```
import { Torch } from '@capawesome/capacitor-torch';

const isAvailable = async () => {
    const result = await Torch.isAvailable();
    return result.available;
};
```

### Turn the torch on and off

Enable or disable the torch. On Android, these methods require SDK 23 or newer. On the Web, you can optionally pass your own `MediaStream` with a video track via the `stream` option:

```
import { Torch } from '@capawesome/capacitor-torch';

const enable = async () => {
  await Torch.enable();
};

const disable = async () => {
  await Torch.disable();
};
```

### Toggle the torch

Switch the torch to the opposite state with a single call:

```
import { Torch } from '@capawesome/capacitor-torch';

const toggle = async () => {
  await Torch.toggle();
};
```

### Check if the torch is enabled

Read the current state of the torch, for example to display the state in your UI:

```
import { Torch } from '@capawesome/capacitor-torch';

const isEnabled = async () => {
    const result = await Torch.isEnabled();
    return result.enabled;
};
```

## API

- [`enable(...)`](#enable)
- [`disable(...)`](#disable)
- [`isAvailable()`](#isavailable)
- [`isEnabled(...)`](#isenabled)
- [`toggle(...)`](#toggle)
- [Interfaces](#interfaces)

### enable(...)

```
enable(options?: EnableOptions | undefined) => Promise<void>
```

Enable the torch.

Only available on Android (SDK 23+), iOS and Web.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `EnableOptions` |

**Since:** 6.0.0

______________________________________________________________________

### disable(...)

```
disable(options?: DisableOptions | undefined) => Promise<void>
```

Disable the torch.

Only available on Android (SDK 23+), iOS and Web.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `DisableOptions` |

**Since:** 6.0.0

______________________________________________________________________

### isAvailable()

```
isAvailable() => Promise<IsAvailableResult>
```

Check if the torch is available.

Only available on Android, iOS and Web.

**Returns:** `Promise<IsAvailableResult>`

**Since:** 6.0.0

______________________________________________________________________

### isEnabled(...)

```
isEnabled(options?: IsEnabledOptions | undefined) => Promise<IsEnabledResult>
```

Check if the torch is enabled.

Only available on Android, iOS and Web.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `IsEnabledOptions` |

**Returns:** `Promise<IsEnabledResult>`

**Since:** 6.0.0

______________________________________________________________________

### toggle(...)

```
toggle(options?: ToggleOptions | undefined) => Promise<void>
```

Toggle the torch.

Only available on Android (SDK 23+), iOS and Web.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `ToggleOptions` |

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### EnableOptions

| Prop         | Type          | Description                                                                                                                                                                                             | Since |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`stream`** | `MediaStream` | The stream of media to enable the torch on. **Attention**: The stream must have a video track. The facing mode of the video track must be the one that corresponds to the torch. Only available on Web. | 6.2.0 |

#### DisableOptions

| Prop         | Type          | Description                                                                                                                                                                                              | Since |
| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`stream`** | `MediaStream` | The stream of media to disable the torch on. **Attention**: The stream must have a video track. The facing mode of the video track must be the one that corresponds to the torch. Only available on Web. | 6.2.0 |

#### IsAvailableResult

| Prop            | Type      | Description                            | Since |
| --------------- | --------- | -------------------------------------- | ----- |
| **`available`** | `boolean` | Whether the torch is available or not. | 6.0.0 |

#### IsEnabledResult

| Prop          | Type      | Description                          | Since |
| ------------- | --------- | ------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether the torch is enabled or not. | 6.0.0 |

#### IsEnabledOptions

| Prop         | Type          | Description                                                                                                                                                                                                          | Since |
| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`stream`** | `MediaStream` | The stream of media to check if the torch is enabled on. **Attention**: The stream must have a video track. The facing mode of the video track must be the one that corresponds to the torch. Only available on Web. | 6.2.0 |

#### ToggleOptions

| Prop         | Type          | Description                                                                                                                                                                                             | Since |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`stream`** | `MediaStream` | The stream of media to toggle the torch on. **Attention**: The stream must have a video track. The facing mode of the video track must be the one that corresponds to the torch. Only available on Web. | 6.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android, iOS and Web. On Android, the `enable(...)`, `disable(...)` and `toggle(...)` methods require SDK 23 or newer. On the Web, the plugin uses the MediaStream API to control the torch.

### Why does `isAvailable` return false on my device?

The `isAvailable()` method reports whether the current device provides a torch. It returns `false` on devices without a torch, for example many tablets or desktop browsers. Use this method to hide or disable your flashlight UI on such devices.

### Do I need any permissions to use this plugin?

On Android, you need to add the `FLASHLIGHT` permission to your `AndroidManifest.xml` file, see the [Installation](#installation) section. No permissions are required on iOS.

### How does the torch control work on the web?

The web implementation uses the MediaStream API. You can optionally pass your own `MediaStream` via the `stream` option of `enable(...)`, `disable(...)`, `isEnabled(...)` and `toggle(...)`. The stream must have a video track, and the facing mode of the video track must be the one that corresponds to the torch.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning.
- [Light Sensor](https://capawesome.io/docs/sdks/capacitor/light-sensor/): Read the device's ambient light sensor.
- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/): Read and control the screen brightness.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/torch/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/torch/LICENSE).

# Capacitor Vault Plugin

Capacitor plugin to securely store key/value pairs in lockable, biometric-protected vaults.

## Features

The Capacitor Vault plugin is one of the most complete secure storage solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Native secure vault on Android and iOS, with a `localStorage`-backed web implementation for development.
- 🔒 **Secure**: Hardware-backed encryption via the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and [iOS Keychain](https://developer.apple.com/documentation/security/keychain-services).
- 🔓 **Lockable**: Unlock once with a biometric or passcode prompt, then perform many read/write operations until `lock()` is called.
- ⏱️ **Auto-lock**: Automatically lock the vault after the app has been backgrounded for a configurable duration.
- 🗂️ **Multi-vault**: Create multiple independent vaults with different configurations on the same device.
- 🔐 **Multiple vault types**: Authenticate with biometrics, the device passcode, or either.
- ♻️ **Key invalidation**: Optionally invalidate the encryption key when the device's biometric set changes.
- 🚨 **Error Codes**: Provides detailed error codes for better error handling.
- ✨ **Customizable**: Customize the authentication prompt with a title, subtitle, and button text.
- 🤝 **Compatibility**: Compatible with the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) and [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Vault plugin is typically used whenever access to stored data should require an explicit user authentication, for example:

- **App lock**: Protect sensitive parts of your app behind a biometric or device-passcode prompt.
- **Password managers**: Store user credentials that are only readable after the user unlocks the vault.
- **Authenticator apps**: Keep TOTP secrets locked until the user authenticates.
- **Master key storage**: Protect the master password or encryption key that guards other data, such as an encrypted database.
- **Session protection**: Automatically lock stored data when the app has been backgrounded for a configurable duration.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.2.x          | >=8.x.x           | Active support |
| 0.1.x          | >=8.x.x           | Deprecated     |

## Demo

A working example can be found [here](https://github.com/capawesome-team/capacitor-vault-demo).

| Android | iOS |
| ------- | --- |
|         |     |

## Guides

- [Announcing the Capacitor Vault Plugin](https://capawesome.io/blog/announcing-the-capacitor-vault-plugin/)
- [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/)
- [Alternative to the Ionic Identity Vault Plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/)

## Videos

- [How to Secure Sensitive Data Using Capacitor Vault Plugin](https://youtu.be/wCNMqVBnQqs?si=mePC0ADiRHy_rFQz)

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-vault` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-vault
npx cap sync
```

### Android

#### Minimum Android version

The `DEVICE_PASSCODE` and `BIOMETRIC_OR_DEVICE_PASSCODE` vault types require Android API 30 (Android 11) or higher. On lower versions, `initialize(...)` will reject with the `AUTHENTICATOR_UNAVAILABLE` error code. The `BIOMETRIC` vault type is supported on all supported Android versions.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### Variables

If needed, you can define the following project variables in your app's `variables.gradle` file to change the default version of the dependencies:

- `$androidxBiometricVersion` version of `androidx.biometric:biometric` (default: `1.1.0`)
- `$androidxLifecycleProcessVersion` version of `androidx.lifecycle:lifecycle-process` (default: `2.9.4`)

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

### iOS

#### Privacy Descriptions

Add the `NSFaceIDUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to Face ID:

```
<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to unlock your data.</string>
```

### Web

**Attention**: The web implementation uses `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to initialize a vault, check whether one exists, unlock and lock it, store and retrieve values, clear or destroy it, and listen for lock and unlock events.

### Initialize the vault

Initialize the vault with the desired configuration once per session before calling any other method. The `lockAfterBackgrounded` option automatically locks the vault after the app has been backgrounded for the given duration in milliseconds:

```
import { Vault, VaultType, ErrorCode } from '@capawesome-team/capacitor-vault';

const options = {
  type: VaultType.Biometric,
  title: 'Unlock vault',
  cancelButtonText: 'Cancel',
  iosFallbackButtonText: 'Use Passcode',
  lockAfterBackgrounded: 30000,
};

// Call once per session before any other method.
const initialize = async () => {
  try {
    await Vault.initialize(options);
  } catch (error) {
    if (error.code === ErrorCode.AuthenticatorUnavailable) {
      // No passcode or biometrics set up.
    } else if (error.code === ErrorCode.KeyInvalidated) {
      // All values are lost; start over.
      await Vault.destroy();
      await Vault.initialize(options);
    } else {
      throw error;
    }
  }
};
```

### Check whether a vault exists

Check whether a vault was created in a previous session, for example to decide between a fresh setup and an unlock flow:

```
import { Vault } from '@capawesome-team/capacitor-vault';

// Check whether a vault was created in a previous session.
const exists = async () => {
  const { exists } = await Vault.exists();
  return exists;
};
```

### Unlock and lock the vault

Unlocking prompts the user for biometric authentication or the device credential, depending on the vault's type. Once unlocked, you can perform many read and write operations until the vault is locked again:

```
import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault';

// Prompt the user for biometric authentication.
const unlock = async () => {
  try {
    await Vault.unlock();
  } catch (error) {
    if (error.code === ErrorCode.UnlockCanceled) {
      console.log('The user canceled the authentication prompt.');
    } else if (error.code === ErrorCode.KeyInvalidated) {
      // All values are lost; start over.
      await Vault.destroy();
      await initialize(); // See "Initialize the vault".
    } else {
      throw error;
    }
  }
};

// Check whether the vault is currently locked.
const isLocked = async () => {
  const { isLocked } = await Vault.isLocked();
  return isLocked;
};

// Lock the vault manually.
const lock = async () => {
  await Vault.lock();
};
```

### Store and retrieve values

Store, retrieve, and remove key/value pairs. The vault must be unlocked before calling these methods:

```
import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault';

// Store a value.
const setValue = async () => {
  await Vault.setValue({ key: 'token', value: 'abc123' });
};

// Retrieve a value.
const getValue = async () => {
  try {
    const { value } = await Vault.getValue({ key: 'token' });
    return value;
  } catch (error) {
    if (error.code === ErrorCode.VaultLocked) {
      // Unlock the vault first.
    } else if (error.code === ErrorCode.DecryptionFailed) {
      // The value is unreadable; remove it.
      await Vault.removeValue({ key: 'token' });
      return null;
    }
    throw error;
  }
};

// Remove a single value.
const removeValue = async () => {
  await Vault.removeValue({ key: 'token' });
};

// List all keys currently stored in the vault.
const getKeys = async () => {
  const { keys } = await Vault.getKeys();
  return keys;
};
```

### Clear or destroy the vault

Remove all values while preserving the vault's configuration, or destroy the vault entirely so that it must be reinitialized before use:

```
import { Vault } from '@capawesome-team/capacitor-vault';

// Remove all values without destroying the vault.
const clear = async () => {
  await Vault.clear();
};

// Permanently destroy the vault.
const destroy = async () => {
  await Vault.destroy();
};
```

### Listen for lock and unlock events

React to the vault being locked or unlocked, for example to navigate to a lock screen when the vault locks:

```
import { Vault } from '@capawesome-team/capacitor-vault';

// React to lock and unlock events.
const addListeners = async () => {
  await Vault.addListener('lock', ({ vaultId, trigger }) => {
    console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`);
  });
  await Vault.addListener('unlock', ({ vaultId }) => {
    console.log(`Vault ${vaultId} unlocked.`);
  });
};
```

## API

- [`clear(...)`](#clear)
- [`destroy(...)`](#destroy)
- [`exists(...)`](#exists)
- [`exportData(...)`](#exportdata)
- [`getKeys(...)`](#getkeys)
- [`getValue(...)`](#getvalue)
- [`importData(...)`](#importdata)
- [`initialize(...)`](#initialize)
- [`isEmpty(...)`](#isempty)
- [`isLocked(...)`](#islocked)
- [`lock(...)`](#lock)
- [`removeValue(...)`](#removevalue)
- [`setValue(...)`](#setvalue)
- [`unlock(...)`](#unlock)
- [`addListener('lock', ...)`](#addlistenerlock-)
- [`addListener('unlock', ...)`](#addlistenerunlock-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### clear(...)

```
clear(options?: ClearOptions | undefined) => Promise<void>
```

Remove all values from the vault while preserving its configuration.

The vault must be unlocked before calling this method.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `ClearOptions` |

**Since:** 0.1.0

______________________________________________________________________

### destroy(...)

```
destroy(options?: DestroyOptions | undefined) => Promise<void>
```

Destroy the vault, removing all values and its configuration.

After calling this method, the vault must be reinitialized before use.

Everything that could be deleted is removed, even if the call rejects.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `DestroyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### exists(...)

```
exists(options?: ExistsOptions | undefined) => Promise<ExistsResult>
```

Check whether a vault with the given identifier exists on the device.

Returns `true` as long as the vault's encryption key or any stored values exist, even if `initialize()` has not been called in the current session. Useful for detecting whether a fresh setup or an unlock flow is required. If the key is gone while values are still stored, `initialize()` rejects with `KEY_INVALIDATED`.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `ExistsOptions` |

**Returns:** `Promise<ExistsResult>`

**Since:** 0.1.0

______________________________________________________________________

### exportData(...)

```
exportData(options?: ExportDataOptions | undefined) => Promise<ExportDataResult>
```

Export all values from the vault as a key/value map.

The vault must be unlocked before calling this method. Values that cannot be decrypted are left out of the map and reported in the `skippedCount` property.

**Note**: Designed for small datasets such as backup/restore flows. The entire set of values is loaded into memory and serialized across the Capacitor bridge in a single call. Avoid using this method on vaults with large amounts of data to prevent out-of-memory errors.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `ExportDataOptions` |

**Returns:** `Promise<ExportDataResult>`

**Since:** 0.1.0

______________________________________________________________________

### getKeys(...)

```
getKeys(options?: GetKeysOptions | undefined) => Promise<GetKeysResult>
```

Get a list of all keys stored in the vault.

The vault must be unlocked before calling this method.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `GetKeysOptions` |

**Returns:** `Promise<GetKeysResult>`

**Since:** 0.1.0

______________________________________________________________________

### getValue(...)

```
getValue(options: GetValueOptions) => Promise<GetValueResult>
```

Get the value associated with a key.

The vault must be unlocked before calling this method.

Rejects with `DECRYPTION_FAILED` if the stored value cannot be decrypted.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `GetValueOptions` |

**Returns:** `Promise<GetValueResult>`

**Since:** 0.1.0

______________________________________________________________________

### importData(...)

```
importData(options: ImportDataOptions) => Promise<void>
```

Import a key/value map into the vault, replacing all existing values.

The vault must be unlocked before calling this method. Any values previously stored in the vault are removed before the new entries are written. On partial failure, the vault may be left in an inconsistent state — callers that need atomicity should call `exportData()` first and re-import on failure.

**Note**: Designed for small datasets such as backup/restore flows. The entire set of values is loaded into memory and serialized across the Capacitor bridge in a single call. Avoid using this method on vaults with large amounts of data to prevent out-of-memory errors.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `ImportDataOptions` |

**Since:** 0.1.0

______________________________________________________________________

### initialize(...)

```
initialize(options: InitializeOptions) => Promise<void>
```

Initialize a vault with the given configuration.

Must be called once per session before any other method.

The `type` and `invalidateOnBiometricEnrollment` options are baked into the encryption key at vault creation and cannot be changed afterwards; values passed for existing vaults are silently ignored.

Rejects with `KEY_INVALIDATED` if the encryption key is gone while encrypted values are still stored. No new key is created in that case, because it could not decrypt them.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEmpty(...)

```
isEmpty(options?: IsEmptyOptions | undefined) => Promise<IsEmptyResult>
```

Check whether the vault contains no values.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `IsEmptyOptions` |

**Returns:** `Promise<IsEmptyResult>`

**Since:** 0.1.0

______________________________________________________________________

### isLocked(...)

```
isLocked(options?: IsLockedOptions | undefined) => Promise<IsLockedResult>
```

Check whether the vault is currently locked.

Rejects with `VAULT_NOT_FOUND` if the vault has not been initialized in the current session.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `IsLockedOptions` |

**Returns:** `Promise<IsLockedResult>`

**Since:** 0.1.0

______________________________________________________________________

### lock(...)

```
lock(options?: LockOptions | undefined) => Promise<void>
```

Lock the vault.

Clears the in-memory encryption key. Stored values remain encrypted on disk and are recoverable via `unlock()`.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `LockOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removeValue(...)

```
removeValue(options: RemoveValueOptions) => Promise<void>
```

Remove the value associated with a key.

The vault must be unlocked before calling this method.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `RemoveValueOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setValue(...)

```
setValue(options: SetValueOptions) => Promise<void>
```

Set the value associated with a key.

The vault must be unlocked before calling this method.

On **Web**, the value is stored unencrypted in `localStorage`. This is for development purposes only and should NOT be used in production.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `SetValueOptions` |

**Since:** 0.1.0

______________________________________________________________________

### unlock(...)

```
unlock(options?: UnlockOptions | undefined) => Promise<void>
```

Unlock the vault.

Prompts the user for biometric authentication or device credential, depending on the vault's `type`.

Rejects with `KEY_INVALIDATED` if the encryption key can no longer be used, for example because the device's biometric set changed or the key was lost while encrypted values are still stored.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `UnlockOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('lock', ...)

```
addListener(eventName: 'lock', listenerFunc: (event: LockEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for vault events.

| Param              | Type                         |
| ------------------ | ---------------------------- |
| **`eventName`**    | `'lock'`                     |
| **`listenerFunc`** | `(event: LockEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('unlock', ...)

```
addListener(eventName: 'unlock', listenerFunc: (event: UnlockEvent) => void) => Promise<PluginListenerHandle>
```

Add a listener for vault events.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'unlock'`                     |
| **`listenerFunc`** | `(event: UnlockEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners registered for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ClearOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### DestroyOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### ExistsResult

| Prop         | Type      | Description                                    | Since |
| ------------ | --------- | ---------------------------------------------- | ----- |
| **`exists`** | `boolean` | Whether or not the vault has been initialized. | 0.1.0 |

#### ExistsOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### ExportDataResult

| Prop               | Type                         | Description                                                                          | Since |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------ | ----- |
| **`data`**         | `{ [key: string]: string; }` | The exported key/value map.                                                          | 0.1.0 |
| **`skippedCount`** | `number`                     | The number of stored values that could not be decrypted and were therefore left out. | 0.2.0 |

#### ExportDataOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### GetKeysResult

| Prop       | Type       | Description                             | Since |
| ---------- | ---------- | --------------------------------------- | ----- |
| **`keys`** | `string[]` | The keys currently stored in the vault. | 0.1.0 |

#### GetKeysOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### GetValueResult

| Prop        | Type     | Description | Since                                                                  |
| ----------- | -------- | ----------- | ---------------------------------------------------------------------- |
| **`value`** | \`string | null\`      | The retrieved value, or `null` if no value is associated with the key. |

#### GetValueOptions

| Prop          | Type     | Description                               | Default     | Since |
| ------------- | -------- | ----------------------------------------- | ----------- | ----- |
| **`key`**     | `string` | The key associated with the stored value. |             | 0.1.0 |
| **`vaultId`** | `string` | The identifier of the vault.              | `'default'` | 0.1.0 |

#### ImportDataOptions

| Prop          | Type                         | Description                                                                            | Default     | Since |
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ----------- | ----- |
| **`data`**    | `{ [key: string]: string; }` | The key/value map to import into the vault. Replaces all existing values in the vault. |             | 0.1.0 |
| **`vaultId`** | `string`                     | The identifier of the vault.                                                           | `'default'` | 0.1.0 |

#### InitializeOptions

| Prop                                  | Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default     | Since |
| ------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----- |
| **`cancelButtonText`**                | `string`    | The text displayed on the cancel button of the authentication prompt. Only available on Android and iOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |             | 0.1.0 |
| **`invalidateOnBiometricEnrollment`** | `boolean`   | Whether the encryption key should be invalidated when the device's biometric set changes (e.g., a new fingerprint or face is enrolled). If `true` and the biometric set changes, the next `unlock()` call rejects with `KEY_INVALIDATED`. The app must call `destroy()` and reinitialize. Per-platform behavior: - **Android**: when biometric is involved, invalidates the entire encryption key. For `BIOMETRIC_OR_DEVICE_PASSCODE` vaults, the device passcode path is also rendered unusable. - **iOS**: when biometric is involved, invalidates the biometric branch only. For `BIOMETRIC_OR_DEVICE_PASSCODE` vaults, the user can still unlock with the device passcode. Only applies to vault types that use biometric authentication. This option only controls whether adding or changing biometric enrollments invalidates the key. On **iOS**, resetting Face ID or Touch ID invalidates a `BIOMETRIC` vault regardless of this option, and the key does not come back after re-enrollment; `unlock(...)` and `initialize(...)` then reject with `KEY_INVALIDATED`. On **Android**, the key survives the removal of all biometrics and `unlock(...)` rejects with `AUTHENTICATOR_UNAVAILABLE` until a biometric is enrolled again. **Note**: This option is baked into the encryption key at vault creation time. The value passed when reinitializing an existing vault is silently ignored. | `false`     | 0.1.0 |
| **`iosFallbackButtonText`**           | `string`    | The text displayed on the fallback button of the authentication prompt. Only available on iOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |             | 0.1.0 |
| **`lockAfterBackgrounded`**           | `number`    | The duration in milliseconds the app must be backgrounded before the vault is automatically locked. If omitted, the vault is never automatically locked. The duration is measured with a monotonic clock, so changing the device time does not affect it. It is evaluated when the app returns to the foreground.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |             | 0.1.0 |
| **`subtitle`**                        | `string`    | The subtitle of the authentication prompt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |             | 0.1.0 |
| **`title`**                           | `string`    | The title of the authentication prompt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |             | 0.1.0 |
| **`type`**                            | `VaultType` | The type of the vault.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |             | 0.1.0 |
| **`vaultId`**                         | `string`    | The identifier of the vault.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'default'` | 0.1.0 |

#### IsEmptyResult

| Prop          | Type      | Description                           | Since |
| ------------- | --------- | ------------------------------------- | ----- |
| **`isEmpty`** | `boolean` | Whether the vault contains no values. | 0.1.0 |

#### IsEmptyOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### IsLockedResult

| Prop           | Type      | Description                            | Since |
| -------------- | --------- | -------------------------------------- | ----- |
| **`isLocked`** | `boolean` | Whether the vault is currently locked. | 0.1.0 |

#### IsLockedOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### LockOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### RemoveValueOptions

| Prop          | Type     | Description                               | Default     | Since |
| ------------- | -------- | ----------------------------------------- | ----------- | ----- |
| **`key`**     | `string` | The key associated with the stored value. |             | 0.1.0 |
| **`vaultId`** | `string` | The identifier of the vault.              | `'default'` | 0.1.0 |

#### SetValueOptions

| Prop          | Type     | Description                               | Default     | Since |
| ------------- | -------- | ----------------------------------------- | ----------- | ----- |
| **`key`**     | `string` | The key associated with the stored value. |             | 0.1.0 |
| **`value`**   | `string` | The value to store.                       |             | 0.1.0 |
| **`vaultId`** | `string` | The identifier of the vault.              | `'default'` | 0.1.0 |

#### UnlockOptions

| Prop          | Type     | Description                  | Default     | Since |
| ------------- | -------- | ---------------------------- | ----------- | ----- |
| **`vaultId`** | `string` | The identifier of the vault. | `'default'` | 0.1.0 |

#### PluginListenerHandle

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

#### LockEvent

| Prop          | Type          | Description                              | Since |
| ------------- | ------------- | ---------------------------------------- | ----- |
| **`trigger`** | `LockTrigger` | What caused the vault to lock.           | 0.1.0 |
| **`vaultId`** | `string`      | The identifier of the vault that locked. | 0.1.0 |

#### UnlockEvent

| Prop          | Type     | Description                                | Since |
| ------------- | -------- | ------------------------------------------ | ----- |
| **`vaultId`** | `string` | The identifier of the vault that unlocked. | 0.1.0 |

### Enums

#### VaultType

| Members                         | Value                            | Description                                                                                                                                                                                                             | Since |
| ------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Biometric`**                 | `'BIOMETRIC'`                    | The vault is unlocked with the device's biometric authentication. Requires a Class 3 (Strong) biometric sensor on Android. Initialization rejects with `AUTHENTICATOR_UNAVAILABLE` if no Strong biometric is available. | 0.1.0 |
| **`BiometricOrDevicePasscode`** | `'BIOMETRIC_OR_DEVICE_PASSCODE'` | The vault is unlocked with either the device's biometric authentication or the device's credential (PIN, pattern, or password).                                                                                         | 0.1.0 |
| **`DevicePasscode`**            | `'DEVICE_PASSCODE'`              | The vault is unlocked with the device's credential (PIN, pattern, or password).                                                                                                                                         | 0.1.0 |

#### LockTrigger

| Members       | Value       | Description                                                                                | Since |
| ------------- | ----------- | ------------------------------------------------------------------------------------------ | ----- |
| **`Manual`**  | `'MANUAL'`  | The vault was locked by an explicit call to `lock()`.                                      | 0.1.0 |
| **`Timeout`** | `'TIMEOUT'` | The vault was locked because the app was backgrounded longer than `lockAfterBackgrounded`. | 0.1.0 |

## FAQ

### Where is the data stored?

On Android, the encryption key is stored in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and the encrypted values are stored in two `SharedPreferences` files per vault. On iOS, both the encryption key and the encrypted values are stored as separate [Keychain](https://developer.apple.com/documentation/security/keychain-services) items.

The encryption key is never included in cloud backups on either platform. On Android, the encrypted values in `SharedPreferences` are part of [Android Auto Backup](https://developer.android.com/identity/data/autobackup) by default, but the backed-up ciphertext is unusable on another device without the Keystore key; to exclude the preference files (`capawesome_capacitor_vault_key_<vaultId>.xml` and `capawesome_capacitor_vault_data_<vaultId>.xml`) from backup, see the [Android documentation](https://developer.android.com/identity/data/autobackup#IncludingFiles). On iOS, the Keychain items use the `*ThisDeviceOnly` accessibility classes, so they are never synced to iCloud Keychain or included in device backups.

### Is the data removed when the app is uninstalled?

On Android, yes: both `SharedPreferences` files and the Keystore key of every vault are deleted. On iOS, no: Keychain items survive an uninstall and are available again after a reinstall with the same bundle identifier. Apple does not document or guarantee this behavior.

To start with empty vaults after a reinstall, keep a marker in `UserDefaults`, which is removed with the app, and call `destroy()` for every vault your app uses on the first launch when it is missing:

```
import { Preferences } from '@capacitor/preferences';
import { Vault } from '@capawesome-team/capacitor-vault';

const destroyAfterReinstall = async () => {
  const { value } = await Preferences.get({ key: 'installed' });
  if (value === null) {
    for (const vaultId of ['default', 'settings']) {
      await Vault.destroy({ vaultId });
    }
    await Preferences.set({ key: 'installed', value: 'true' });
  }
};
```

### When should I use Vault instead of Secure Preferences or SQLite?

All three plugins protect data on the device, but they target different problems:

- **[Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/)** is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background — typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information.
- **[SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/)** is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets — for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database.
- **Vault** (this plugin) is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action — a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an "app lock" screen.

A quick decision tree:

- Need queries, relations, or large datasets? → **SQLite**.
- Need encrypted key/value storage the app can read freely in the background? → **Secure Preferences**.
- Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? → **Vault**.

The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else.

### Is this plugin an alternative to Ionic Identity Vault?

Yes. This plugin was built as an alternative to [Ionic Identity Vault](https://ionic.io/products/identity-vault) and offers a similar feature set:

- Hardware-backed encryption using the Android Keystore and iOS Keychain
- Biometric, device passcode, or combined authentication
- Lockable session model with manual lock and auto-lock on background
- Multiple independent vaults per device
- Key invalidation when the device's biometric set changes

### How do I migrate from Ionic Identity Vault?

For an AI-assisted migration of your code, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool and use the `ionic-enterprise-sdk-migration` skill to migrate your project to `@capawesome-team/capacitor-vault`. Alternatively, you can follow the manual instructions and the complete runtime migration example in the blog post [Alternative to the Ionic Identity Vault plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/).

The stored data needs to be migrated at runtime while **both** plugins are still installed: Identity Vault exposes `exportVault()`, which returns a plain key/value map after the user unlocks the vault, and that map has the exact shape expected by this plugin's [`importData(...)`](#importdata) method, so the two can be bridged directly. Note that the user has to authenticate once during the migration to unlock the old vault — this is unavoidable, since the data is protected by the device's biometric or passcode authentication by design. Once all users have migrated (for example, after a release cycle in which everyone has opened the app at least once), you can remove the Identity Vault dependency in a follow-up release.

### What happens when the user enrolls a new fingerprint or face?

If the vault was created with the `invalidateOnBiometricEnrollment` option set to `true`, the encryption key is invalidated when the device's biometric set changes, and the next `unlock()` call rejects with the `KEY_INVALIDATED` error code. The app must then call `destroy()` and reinitialize the vault. On Android, the entire encryption key is invalidated, while on iOS only the biometric branch is invalidated, so users of `BIOMETRIC_OR_DEVICE_PASSCODE` vaults can still unlock with the device passcode. Note that this option is baked into the encryption key at vault creation time and cannot be changed afterwards.

The `invalidateOnBiometricEnrollment` option only controls whether adding or changing biometric enrollments invalidates the key. Resetting the biometric enrollment entirely is a separate case: on iOS, removing all enrolled biometrics invalidates a `BIOMETRIC` vault regardless of this option, and the key does not come back after re-enrollment, so `unlock()` and `initialize()` reject with the `KEY_INVALIDATED` error code. On Android, the key survives the removal of all biometrics and `unlock()` rejects with `AUTHENTICATOR_UNAVAILABLE` until a biometric is enrolled again.

The same error code is reported whenever the encryption key is gone while encrypted values are still stored, for example after the device passcode was removed on iOS. `initialize()` and `unlock()` reject in that case instead of creating a new key, because a new key could not decrypt the existing values. The recovery is always the same: call `destroy()` and initialize the vault again.

On iOS, each vault consists of two kinds of Keychain items: the key item holding the encryption key and one data item per stored value.

### Can I use this plugin on the Web?

The web implementation stores values unencrypted in `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production. The secure, hardware-backed vault is only available on Android and iOS.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition.
- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information.
- [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/): Access SQLite databases with support for encryption, transactions, and schema migrations.

## Next steps

Here are a few resources to help you continue:

- Read [Alternative to the Ionic Identity Vault plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/) if you are migrating from Ionic Identity Vault.
- Need simple secure key/value storage without vault locking? Check out the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/).
- Check out [Getting Started with Insiders](https://capawesome.io/docs/insiders/getting-started/) to learn how to install the plugin.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/LICENSE).

# Capacitor Volume Plugin

Capacitor plugin to control the volume and observe hardware volume button presses.

## Features

- 🔊 **Volume control**: Get and set the volume level.
- 🎚️ **Audio streams**: Control individual audio streams (music, ring, alarm and more) on Android.
- 🔘 **Volume buttons**: Listen for hardware volume button presses.
- 🤫 **Suppression**: Keep the volume unchanged and hide the system volume indicator while watching.
- 👂 **Change events**: Listen for changes to the volume level.
- 🤝 **Compatibility**: Works alongside the [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/), [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/) and [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Volume plugin is typically used whenever an app needs to control the volume or react to the hardware volume buttons, for example:

- **Media apps**: Read and adjust the media volume from your own player UI.
- **Camera apps**: Use the hardware volume buttons as a shutter trigger while keeping the volume unchanged.
- **Remote control apps**: Map the volume buttons to custom actions, for example to control external devices.
- **Audio guidance**: Warn users when the volume is too low to hear important audio cues.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-volume` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-volume
npx cap sync
```

This plugin is only available on **Android** and **iOS**. On the Web, all methods reject as unimplemented.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to get and set the current volume, watch the hardware volume buttons, listen for volume button presses and volume changes, and remove all listeners.

### Get the current volume

Read the current volume level as a value between `0` and `1`. On Android, you can select the audio stream (for example the ring stream) with the `stream` option. On iOS, this always returns the media volume:

```
import { Volume, VolumeStream } from '@capawesome/capacitor-volume';

const getVolume = async () => {
  const { volume } = await Volume.getVolume();
  return volume;
};

const getRingVolume = async () => {
  const { volume } = await Volume.getVolume({ stream: VolumeStream.Ring });
  return volume;
};
```

### Set the volume

Set the volume level as a value between `0` and `1`. On Android, you can select the audio stream with the `stream` option. On iOS, this always sets the media volume:

```
import { Volume } from '@capawesome/capacitor-volume';

const setVolume = async () => {
  await Volume.setVolume({ volume: 0.5 });
};
```

### Watch the hardware volume buttons

Start watching the hardware volume buttons to receive the `volumeButtonPressed` and `volumeChange` events. With the `suppressVolumeChange` option enabled, the volume level is kept unchanged and the system volume indicator is hidden while watching:

```
import { Volume } from '@capawesome/capacitor-volume';

const startWatching = async () => {
  await Volume.startWatching({ suppressVolumeChange: true });
};

const stopWatching = async () => {
  await Volume.stopWatching();
};

const isWatching = async () => {
  const { watching } = await Volume.isWatching();
  return watching;
};
```

### Listen for volume button presses

Get notified when a hardware volume button is pressed. The event is only emitted while watching (see above):

```
import { Volume } from '@capawesome/capacitor-volume';

const addVolumeButtonPressedListener = async () => {
  await Volume.addListener('volumeButtonPressed', event => {
    console.log('Volume button pressed:', event.direction);
  });
};
```

### Listen for volume changes

Get notified when the volume level changes. The event is only emitted while watching (see above):

```
import { Volume } from '@capawesome/capacitor-volume';

const addVolumeChangeListener = async () => {
  await Volume.addListener('volumeChange', event => {
    console.log('Volume changed:', event.volume);
  });
};
```

### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { Volume } from '@capawesome/capacitor-volume';

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

## API

- [`getVolume(...)`](#getvolume)
- [`isWatching()`](#iswatching)
- [`setVolume(...)`](#setvolume)
- [`startWatching(...)`](#startwatching)
- [`stopWatching()`](#stopwatching)
- [`addListener('volumeButtonPressed', ...)`](#addlistenervolumebuttonpressed-)
- [`addListener('volumeButtonReleased', ...)`](#addlistenervolumebuttonreleased-)
- [`addListener('volumeChange', ...)`](#addlistenervolumechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### getVolume(...)

```
getVolume(options?: GetVolumeOptions | undefined) => Promise<GetVolumeResult>
```

Get the current volume level.

On iOS, this always returns the media volume.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GetVolumeOptions` |

**Returns:** `Promise<GetVolumeResult>`

**Since:** 0.1.0

______________________________________________________________________

### isWatching()

```
isWatching() => Promise<IsWatchingResult>
```

Check whether the hardware volume buttons are currently being watched.

Only available on Android and iOS.

**Returns:** `Promise<IsWatchingResult>`

**Since:** 0.1.0

______________________________________________________________________

### setVolume(...)

```
setVolume(options: SetVolumeOptions) => Promise<void>
```

Set the volume level.

On iOS, this always sets the media volume.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetVolumeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### startWatching(...)

```
startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
```

Start watching the hardware volume buttons.

The `volumeButtonPressed`, `volumeButtonReleased` and `volumeChange` events are only emitted while watching.

If the volume buttons are already being watched, this call has no effect. Call `stopWatching()` first to change the options.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `StartWatchingOptions` |

**Since:** 0.1.0

______________________________________________________________________

### stopWatching()

```
stopWatching() => Promise<void>
```

Stop watching the hardware volume buttons.

On iOS, this also restores the volume level that was set when watching started if the `suppressVolumeChange` option was enabled.

Only available on Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### addListener('volumeButtonPressed', ...)

```
addListener(eventName: 'volumeButtonPressed', listenerFunc: (event: VolumeButtonPressedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a hardware volume button is pressed while watching.

Only available on Android and iOS.

| Param              | Type                                        |
| ------------------ | ------------------------------------------- |
| **`eventName`**    | `'volumeButtonPressed'`                     |
| **`listenerFunc`** | `(event: VolumeButtonPressedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('volumeButtonReleased', ...)

```
addListener(eventName: 'volumeButtonReleased', listenerFunc: (event: VolumeButtonReleasedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a hardware volume button is released while watching.

Only available on Android.

| Param              | Type                                         |
| ------------------ | -------------------------------------------- |
| **`eventName`**    | `'volumeButtonReleased'`                     |
| **`listenerFunc`** | `(event: VolumeButtonReleasedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.0

______________________________________________________________________

### addListener('volumeChange', ...)

```
addListener(eventName: 'volumeChange', listenerFunc: (event: VolumeChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the volume level changes while watching.

On Android, this is called for changes to the music stream. On iOS, this is called for changes to the media volume and is not called while the `suppressVolumeChange` option is enabled.

Only available on Android and iOS.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'volumeChange'`                     |
| **`listenerFunc`** | `(event: VolumeChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetVolumeResult

| Prop         | Type     | Description                                              | Since |
| ------------ | -------- | -------------------------------------------------------- | ----- |
| **`volume`** | `number` | The current volume level as a value between `0` and `1`. | 0.1.0 |

#### GetVolumeOptions

| Prop         | Type           | Description                                                        | Default              | Since |
| ------------ | -------------- | ------------------------------------------------------------------ | -------------------- | ----- |
| **`stream`** | `VolumeStream` | The audio stream to get the volume for. Only available on Android. | `VolumeStream.Music` | 0.1.0 |

#### IsWatchingResult

| Prop           | Type      | Description                                                      | Since |
| -------------- | --------- | ---------------------------------------------------------------- | ----- |
| **`watching`** | `boolean` | Whether the hardware volume buttons are currently being watched. | 0.1.0 |

#### SetVolumeOptions

| Prop         | Type           | Description                                                        | Default              | Since |
| ------------ | -------------- | ------------------------------------------------------------------ | -------------------- | ----- |
| **`stream`** | `VolumeStream` | The audio stream to set the volume for. Only available on Android. | `VolumeStream.Music` | 0.1.0 |
| **`volume`** | `number`       | The volume level to set as a value between `0` and `1`.            |                      | 0.1.0 |

#### StartWatchingOptions

| Prop                       | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default | Since |
| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`suppressVolumeChange`** | `boolean` | Whether to keep the volume level unchanged when a hardware volume button is pressed while watching. On Android, the volume key events are consumed so that the system does not apply the volume change or display the volume panel. On iOS, the volume level is reset immediately after each button press and the system volume indicator is hidden. If the volume level is close to the minimum or maximum, it is nudged to a value from which both buttons can still be detected. The original volume level is restored when watching stops. | `false` | 0.1.0 |

#### PluginListenerHandle

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

#### VolumeButtonPressedEvent

| Prop            | Type        | Description                                          | Since |
| --------------- | ----------- | ---------------------------------------------------- | ----- |
| **`direction`** | `Direction` | The direction of the pressed hardware volume button. | 0.1.0 |

#### VolumeButtonReleasedEvent

| Prop            | Type        | Description                                           | Since |
| --------------- | ----------- | ----------------------------------------------------- | ----- |
| **`direction`** | `Direction` | The direction of the released hardware volume button. | 0.2.0 |

#### VolumeChangeEvent

| Prop         | Type     | Description                                          | Since |
| ------------ | -------- | ---------------------------------------------------- | ----- |
| **`volume`** | `number` | The new volume level as a value between `0` and `1`. | 0.1.0 |

### Type Aliases

#### Direction

The direction of a hardware volume button.

- `up`: The volume up button.
- `down`: The volume down button.

`'down' | 'up'`

### Enums

#### VolumeStream

| Members            | Value            | Description                                    | Since |
| ------------------ | ---------------- | ---------------------------------------------- | ----- |
| **`Alarm`**        | `'ALARM'`        | The audio stream for alarms.                   | 0.1.0 |
| **`Music`**        | `'MUSIC'`        | The audio stream for music and media playback. | 0.1.0 |
| **`Notification`** | `'NOTIFICATION'` | The audio stream for notifications.            | 0.1.0 |
| **`Ring`**         | `'RING'`         | The audio stream for the phone ring.           | 0.1.0 |
| **`System`**       | `'SYSTEM'`       | The audio stream for system sounds.            | 0.1.0 |
| **`VoiceCall`**    | `'VOICE_CALL'`   | The audio stream for phone calls.              | 0.1.0 |

## Volume Control

Keep the following platform differences in mind when getting and setting the volume:

- **Android**: The volume can be read and set per audio stream (see the `stream` option). If Do Not Disturb is active, changing the volume of the ring, notification or system stream requires Do Not Disturb access. Without this access, the call is rejected with the `DO_NOT_DISTURB_ACCESS_REQUIRED` error code. You can direct the user to the corresponding settings screen using the [`ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS`](https://developer.android.com/reference/android/provider/Settings#ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS) intent, for example with the [App Launcher](https://capacitorjs.com/docs/apis/app-launcher) plugin.
- **iOS**: There is no public API to set the system volume directly. The plugin therefore uses a hidden system volume view to change the media volume, which is the only volume that can be read and set. The `stream` option is ignored.

## Volume Button Watching

Keep the following platform differences in mind when watching the hardware volume buttons:

- **Android**: The volume key events are intercepted by the web view, so button presses are only detected while the app is in the foreground. With the `suppressVolumeChange` option enabled, the key events are consumed, which keeps the volume unchanged and prevents the system volume panel from appearing.
- **iOS**: Button presses are derived from changes to the media volume, so button presses are only detected while the app is in the foreground. Without the `suppressVolumeChange` option, presses can not be detected once the volume has reached its minimum or maximum. With the option enabled, the volume is reset immediately after each press (nudged away from the edges if needed), the system volume indicator is hidden, and the original volume is restored when watching stops. Note that volume changes from other sources (for example Control Center) are also reported while watching.

## FAQ

### How is this plugin different from other similar plugins?

It combines volume control and hardware button events in one unified API — a natural fit on iOS, where both rely on the same underlying system machinery. It adds per-stream control on Android and handles iOS volume-indicator suppression, all through a fully typed, actively maintained package, so a single dependency covers the whole volume story.

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented.

### Why is the `stream` option ignored on iOS?

On iOS, there is no public API to set the system volume directly. The plugin therefore uses a hidden system volume view to change the media volume, which is the only volume that can be read and set on iOS. The `stream` option is only supported on Android, see [Volume Control](#volume-control) for details.

### Why is `setVolume` rejected with the `DO_NOT_DISTURB_ACCESS_REQUIRED` error code?

On Android, changing the volume of the ring, notification or system stream while Do Not Disturb is active requires Do Not Disturb access. You can direct the user to the corresponding settings screen using the `ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS` intent, for example with the App Launcher plugin, see [Volume Control](#volume-control) for details.

### Why are volume button presses not detected?

The `volumeButtonPressed` event is only emitted while watching, so make sure you have called `startWatching(...)` first. On both platforms, button presses are only detected while the app is in the foreground. On iOS, presses can also not be detected once the volume has reached its minimum or maximum unless the `suppressVolumeChange` option is enabled, see [Volume Button Watching](#volume-button-watching) for details.

### What does the `suppressVolumeChange` option do?

With this option enabled, pressing a hardware volume button while watching does not change the volume and the system volume indicator stays hidden. On Android, the volume key events are consumed. On iOS, the volume level is reset immediately after each button press and the original volume level is restored when watching stops.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session.
- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons.
- [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/): Detect whether the device is in silent mode.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/LICENSE).

# Capacitor Wallet Plugin

Capacitor plugin for adding passes to [Apple Wallet](https://developer.apple.com/documentation/passkit) and [Google Wallet](https://developers.google.com/wallet).

## Features

- 🍎 **Apple Wallet**: Add passes such as tickets, loyalty cards, coupons and boarding passes to Apple Wallet.
- 🤖 **Google Wallet**: Save passes to Google Wallet using the official "Save to Wallet" flow.
- ✅ **Availability check**: Check whether passes can be added on the current device before showing the UI.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Wallet plugin is typically used to hand digital passes to the user's wallet app, for example:

- **Boarding passes**: Add flight or train boarding passes so travelers have them ready at the gate.
- **Event tickets**: Add tickets for concerts, sports events, or the cinema.
- **Loyalty cards**: Let customers store membership and loyalty cards in their wallet.
- **Coupons**: Distribute coupons and vouchers that users can redeem in store.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-wallet` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-wallet
npx cap sync
```

This plugin presents passes only. Passes must be **created and signed on your server**. See [Creating Passes](#creating-passes) below.

### iOS

Adding passes to Apple Wallet via `PKAddPassesViewController` does not require any special entitlement. The `com.apple.developer.pass-type-identifiers` entitlement is only needed if you want to read or manage passes that your app owns, which is out of scope for this plugin.

### Android

No additional permissions or Gradle variables are required. The plugin opens the Google Wallet "Save to Wallet" flow, which is handled by the Google Wallet app or the device's browser.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to check whether passes can be added, add passes to Apple Wallet, and save a pass to Google Wallet.

### Check whether passes can be added

On some devices (e.g. certain iPads) or when adding passes is restricted, passes cannot be added to Apple Wallet. Use this method to gate the UI that triggers `addPasses(...)`. Only available on iOS:

```
import { Wallet } from '@capawesome/capacitor-wallet';

const canAddPasses = async () => {
  const { canAdd } = await Wallet.canAddPasses();
  return canAdd;
};
```

### Add passes to Apple Wallet

Present the system add-pass sheet with one or more passes. Each pass must be a base64-encoded `.pkpass` file that was created and signed on your server (see [Creating Passes](#creating-passes)). Only available on iOS:

```
import { Wallet } from '@capawesome/capacitor-wallet';

const addPasses = async (passes: string[]) => {
  // `passes` are base64-encoded `.pkpass` files that were signed on your server.
  await Wallet.addPasses({ passes });
};
```

### Save a pass to Google Wallet

Open the Google Wallet "Save to Wallet" flow with a signed JWT that was created on your server (see [Creating Passes](#creating-passes)). Only available on Android:

```
import { Wallet } from '@capawesome/capacitor-wallet';

const saveToGoogleWallet = async (jwt: string) => {
  // `jwt` is a signed Google Wallet JWT that was created on your server.
  await Wallet.saveToGoogleWallet({ jwt });
};
```

## API

- [`addPasses(...)`](#addpasses)
- [`canAddPasses()`](#canaddpasses)
- [`saveToGoogleWallet(...)`](#savetogooglewallet)
- [Interfaces](#interfaces)

### addPasses(...)

```
addPasses(options: AddPassesOptions) => Promise<void>
```

Add one or more passes to Apple Wallet.

The passes must be created and signed on your server. This method only presents the system add-pass sheet with the provided passes.

Only available on iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `AddPassesOptions` |

**Since:** 0.1.0

______________________________________________________________________

### canAddPasses()

```
canAddPasses() => Promise<CanAddPassesResult>
```

Check whether passes can be added to Apple Wallet.

This may return `false` on some devices (e.g. certain iPads) or when adding passes is restricted. Use this to gate the UI that triggers `addPasses`.

Only available on iOS.

**Returns:** `Promise<CanAddPassesResult>`

**Since:** 0.1.0

______________________________________________________________________

### saveToGoogleWallet(...)

```
saveToGoogleWallet(options: SaveToGoogleWalletOptions) => Promise<void>
```

Save a pass to Google Wallet.

This opens the Google Wallet "Save to Wallet" flow using the provided JWT. The JWT must be created and signed on your server.

**Note**: With the URL-based flow there is no completion signal, so the promise resolves as soon as the flow is launched, not when the pass is actually saved.

Only available on Android.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SaveToGoogleWalletOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### AddPassesOptions

| Prop         | Type       | Description                                                                                                           | Since |
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **`passes`** | `string[]` | The passes to add to Apple Wallet. Each entry must be a base64-encoded `.pkpass` file that was signed on your server. | 0.1.0 |

#### CanAddPassesResult

| Prop         | Type      | Description                                  | Since |
| ------------ | --------- | -------------------------------------------- | ----- |
| **`canAdd`** | `boolean` | Whether passes can be added to Apple Wallet. | 0.1.0 |

#### SaveToGoogleWalletOptions

| Prop      | Type     | Description                                                   | Since |
| --------- | -------- | ------------------------------------------------------------- | ----- |
| **`jwt`** | `string` | The signed Google Wallet JWT that was created on your server. | 0.1.0 |

## Creating Passes

This plugin only **presents** passes to the user. Creating and signing passes must happen on your server, because it requires private keys and certificates that must never be shipped inside your app.

### Apple Wallet

A pass is a signed `.pkpass` bundle. Build and sign it on your server using your Pass Type ID certificate, then send the resulting file to your app as a base64-encoded string and pass it to `addPasses(...)`. See Apple's [Wallet documentation](https://developer.apple.com/documentation/walletpasses) for details on building and signing passes.

### Google Wallet

A pass is represented by a signed JWT. Create and sign the JWT on your server using your Google Wallet service account, then send it to your app and pass it to `saveToGoogleWallet(...)`. See Google's [Wallet API documentation](https://developers.google.com/wallet) for details on creating passes and JWTs.

**Note**: With the URL-based "Save to Wallet" flow used by this plugin, there is no completion signal, so `saveToGoogleWallet(...)` resolves as soon as the flow is launched, not when the pass is actually saved.

## FAQ

### How is this plugin different from other similar plugins?

It covers both Apple Wallet and Google Wallet from a single fully typed API, presenting signed `.pkpass` passes on iOS and opening the official Google Wallet "Save to Wallet" flow on Android, with an availability check to gate your UI beforehand. It keeps a clean security boundary by presenting passes only — signing stays on your server, where your keys belong — and the README links the official Apple and Google guidance for creating them. The plugin is actively maintained against the latest Capacitor and OS versions.

### Can this plugin create passes for me?

No, this plugin only presents passes to the user. Creating and signing passes must happen on your server, because it requires private keys and certificates that must never be shipped inside your app. See [Creating Passes](#creating-passes) for details and links to the official Apple and Google documentation.

### Which methods are available on which platform?

The `addPasses(...)` and `canAddPasses()` methods are only available on iOS, where they interact with Apple Wallet. The `saveToGoogleWallet(...)` method is only available on Android, where it opens the Google Wallet "Save to Wallet" flow.

### Why does `saveToGoogleWallet` resolve before the pass is saved?

The plugin uses the URL-based "Save to Wallet" flow, which does not provide a completion signal. The promise therefore resolves as soon as the flow is launched, not when the pass is actually saved.

### Do I need a special entitlement to add passes on iOS?

No, adding passes via the system add-pass sheet does not require any special entitlement. The `com.apple.developer.pass-type-identifiers` entitlement is only needed if you want to read or manage passes that your app owns, which is out of scope for this plugin.

### Why does `canAddPasses` return false?

The `canAddPasses()` method may return `false` on some devices (e.g. certain iPads) or when adding passes is restricted. Use it to hide or disable the UI that triggers `addPasses(...)` in these cases.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Purchases](https://capawesome.io/docs/sdks/capacitor/purchases/): Support in-app purchases in your Capacitor app.
- [Square Mobile Payments](https://capawesome.io/docs/sdks/capacitor/square-mobile-payments/): Accept payments with the Square Mobile Payments SDK.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/wallet/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/wallet/LICENSE).

# Capacitor Watch Plugin

Capacitor plugin for communicating with Apple Watch and Wear OS apps. Send messages, sync state and queue transfers between your Capacitor app and your native watch app with a single, unified API.

## Features

The Capacitor Watch plugin is a communication bridge between your Capacitor app and your native watch app. You build your watch UI natively (SwiftUI on watchOS, whatever you prefer on Wear OS) and use this plugin to exchange data with it. Here are some of the key features:

- 💬 **Messaging**: Send live messages with optional request/reply semantics.
- 🔄 **State Sync**: Share the latest state between phone and watch, even across app restarts.
- 📦 **Queued Transfers**: Queue data for guaranteed delivery, even if the watch is currently not reachable.
- 📡 **Reachability**: Query the connection info and get notified when the reachability changes.
- 🌙 **Background Reception**: Data received while the app is closed is replayed as soon as your listeners are registered. On Android, the data is persisted and even survives an app restart.
- ⌚ **Watch SDKs**: Ships with native SDKs for watchOS (Swift Package) and Wear OS (Kotlin library) for the watch side.
- 🧩 **Zero Boilerplate**: No `AppDelegate` or `MainActivity` modifications required.
- 🤝 **Compatibility**: Works hand in hand with the [Health](https://capawesome.io/docs/sdks/capacitor/health/) and [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Watch plugin is typically used whenever an app wants to extend its experience to the wrist, for example:

- **Fitness and health**: Start and stop workouts from the watch and mirror live stats from the phone.
- **Remote control**: Control media playback, smart home devices or timers from the watch.
- **Glanceable data**: Keep the latest scores, tasks or account balances in sync with the watch app.
- **Quick actions**: Confirm orders, check in or trigger phone-side actions with a tap on the watch.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Guides

- [Announcing the Capacitor Watch Plugin](https://capawesome.io/blog/announcing-the-capacitor-watch-plugin/): A tour of the three communication channels, the watch-side SDKs, and how the plugin behaves while your app is closed.
- [How to Build a Wear OS App for Your Capacitor App](https://capawesome.io/blog/how-to-build-a-wear-os-app-for-your-capacitor-app/): Add a native Kotlin watch module and exchange messages, state, and transfers with this plugin.
- [How to Build an Apple Watch App for Your Capacitor App](https://capawesome.io/blog/how-to-build-an-apple-watch-app-for-your-capacitor-app/): Add a native SwiftUI watch target, wire in the watchOS SDK, and exchange messages, state, and transfers with this plugin.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-watch` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-watch
npx cap sync
```

### Android

The plugin registers a `WearableListenerService` in its own manifest, so messages and data from the watch are received even while your app is closed. No manifest changes are required.

This plugin requires Google Play services. On devices without Google Play services, all plugin methods reject as unavailable.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$playServicesWearableVersion` version of `com.google.android.gms:play-services-wearable` (default: `20.0.1`)

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

### iOS

No additional steps are required for the phone side. The plugin activates the `WCSession` automatically when it is loaded, so you do **not** need to modify your `AppDelegate`.

This plugin is the phone side of the bridge. To exchange data, you also need a native watch app. The plugin ships with watch-side SDKs for both platforms, so the watch side is just as simple.

### watchOS

The watchOS SDK is a Swift Package located at `node_modules/@capawesome-team/capacitor-watch/sdks/watchos`. It wires up the `WCSession` for you and exposes an `ObservableObject` that you can use directly in SwiftUI.

Follow these steps to add a watch app to your Capacitor project:

1. Open your app's Xcode project (`ios/App/App.xcodeproj`) — or the Xcode workspace (`ios/App/App.xcworkspace`) if your app uses CocoaPods.
1. Select **File > New > Target…**, choose the **watchOS** tab and select the **Watch App for Existing iOS App** template.
1. If no companion app is selectable, make sure you opened the dialog via **File > New > Target…** (not **File > New > Project…**) and that the **Project** dropdown at the bottom of the dialog points to your app's project.
1. Enter a product name (e.g. `watch`) and select **SwiftUI** as interface. The bundle identifier of the watch app must be prefixed with the bundle identifier of your iOS app (e.g. `com.example.app.watchkitapp`), which Xcode derives automatically.
1. Select **File > Add Package Dependencies… > Add Local…** and select the `node_modules/@capawesome-team/capacitor-watch/sdks/watchos` folder. Add the `CapawesomeWatchSDK` product to your **watch app target** (not the iOS app target).
1. Activate the session and start communicating:

```
import SwiftUI
import CapawesomeWatchSDK

struct ContentView: View {
    @ObservedObject private var watch = CapawesomeWatch.shared

    var body: some View {
        VStack {
            Text(watch.reachable ? "Reachable" : "Not reachable")
            Button("Send Message") {
                watch.sendMessage(["text": "Hello from the watch!"])
            }
        }
        .onAppear {
            watch.onMessageReceived = { data, reply in
                print("Message received:", data)
                reply?(["text": "Hello back!"])
            }
            watch.activate()
        }
    }
}
```

You can find a complete minimal watch app in the [`example/watchos`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/watch/example/watchos) folder. When adding these files to your watch app target, enable **Copy items if needed**, select only the watch app as target and do not create a bridging header (the sources are pure Swift).

**Note**: The local package reference is resolved relative to your Xcode project. Make sure `node_modules` is installed before opening the project.

### Wear OS

The Wear OS SDK is a Kotlin library located at `node_modules/@capawesome-team/capacitor-watch/sdks/wearos`. It provides send helpers and a listener service base class for the watch side.

Wear OS communication has two hard requirements imposed by the Google Play services Data Layer:

- The Wear OS module must use the **same `applicationId`** as your phone app.
- Both apps must be signed with the **same signing certificate**.

Follow these steps to add a Wear OS app to your Capacitor project:

1. Create a new module folder `android/wear` for the watch app. You can copy the minimal example from the [`example/wearos`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/watch/example/wearos) folder as a starting point (make sure to change the `applicationId` to your app's id).
1. Include the watch app module and the Wear OS SDK in your `android/settings.gradle` file:

```
include ':wear'
include ':capawesome-watch-sdk'
project(':capawesome-watch-sdk').projectDir = new File('../node_modules/@capawesome-team/capacitor-watch/sdks/wearos')
```

1. Add the SDK as a dependency to your `android/wear/build.gradle` file:

```
dependencies {
    implementation project(':capawesome-watch-sdk')
}
```

1. Declare the capability that the phone side uses to discover your watch app in `android/wear/src/main/res/values/wear.xml`:

```
<resources>
    <string-array name="android_wear_capabilities">
        <item>capawesome_watch</item>
    </string-array>
</resources>
```

1. Create a listener service by extending the `WatchListenerService` base class:

```
class MyWatchListenerService : WatchListenerService() {
    override fun onMessageReceived(data: JSONObject, reply: ((JSONObject) -> Unit)?) {
        reply?.invoke(JSONObject().put("text", "Hello back!"))
    }

    override fun onStateReceived(data: JSONObject) {}

    override fun onUserInfoReceived(data: JSONObject) {}
}
```

1. Register the service in the manifest of your watch app:

```
<service
    android:name=".MyWatchListenerService"
    android:exported="true">
    <intent-filter>
        <action android:name="com.google.android.gms.wearable.MESSAGE_RECEIVED" />
        <action android:name="com.google.android.gms.wearable.DATA_CHANGED" />
        <data
            android:scheme="wear"
            android:host="*"
            android:pathPrefix="/capawesome/watch" />
    </intent-filter>
</service>
```

1. Send data to the phone using the `CapawesomeWatch` class. All methods are `suspend` functions, so they must be called from a coroutine:

```
val watch = CapawesomeWatch(context)
val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)

scope.launch {
    watch.sendMessage(JSONObject().put("text", "Hello from the watch!"))
    val reply = watch.sendMessageForReply(JSONObject().put("text", "Hello from the watch!"))
    watch.updateState(JSONObject().put("counter", 42))
    watch.transferUserInfo(JSONObject().put("sentAt", System.currentTimeMillis()))
}
```

## Configuration

On Android, the plugin discovers your watch app via the capability that the watch app declares (see the Wear OS setup above). You can configure the capability string in your `capacitor.config.ts` file:

```
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Watch: {
      capability: 'capawesome_watch',
    },
  },
};

export default config;
```

- `capability` (string): The capability that the Wear OS watch app declares. Only available on Android. Default: `capawesome_watch`.

On iOS, no configuration is required.

## Usage

The plugin exposes three communication channels with different delivery guarantees — see [Communication Channels](#communication-channels) for how they map to the platform APIs.

```
import { Watch } from '@capawesome-team/capacitor-watch';

const getConnectionInfo = async () => {
  const { reachable, paired, watchAppInstalled } = await Watch.getConnectionInfo();
  return { reachable, paired, watchAppInstalled };
};

const sendMessage = async () => {
  await Watch.sendMessage({ data: { text: 'Hello from the phone!' } });
};

const sendMessageWithReply = async () => {
  const { reply } = await Watch.sendMessage({
    data: { text: 'Hello from the phone!' },
    expectsReply: true,
  });
  return reply;
};

const updateState = async () => {
  await Watch.updateState({ data: { counter: 42 } });
};

const transferUserInfo = async () => {
  await Watch.transferUserInfo({ data: { sentAt: Date.now() } });
};

const addListeners = async () => {
  await Watch.addListener('messageReceived', async event => {
    if (event.messageId) {
      await Watch.replyToMessage({
        data: { text: 'Hello back!' },
        messageId: event.messageId,
      });
    }
  });
  await Watch.addListener('reachabilityChange', event => {
    console.log('Reachable:', event.reachable);
  });
  await Watch.addListener('stateReceived', event => {
    console.log('State received:', event.data);
  });
  await Watch.addListener('userInfoReceived', event => {
    console.log('User info received:', event.data);
  });
};
```

## API

- [`getConnectionInfo()`](#getconnectioninfo)
- [`getReceivedState()`](#getreceivedstate)
- [`replyToMessage(...)`](#replytomessage)
- [`sendMessage(...)`](#sendmessage)
- [`transferUserInfo(...)`](#transferuserinfo)
- [`updateState(...)`](#updatestate)
- [`addListener('messageReceived', ...)`](#addlistenermessagereceived-)
- [`addListener('reachabilityChange', ...)`](#addlistenerreachabilitychange-)
- [`addListener('stateReceived', ...)`](#addlistenerstatereceived-)
- [`addListener('userInfoReceived', ...)`](#addlisteneruserinforeceived-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)

### getConnectionInfo()

```
getConnectionInfo() => Promise<GetConnectionInfoResult>
```

Get information about the connection to the watch.

Only available on Android and iOS.

**Returns:** `Promise<GetConnectionInfoResult>`

**Since:** 0.0.1

______________________________________________________________________

### getReceivedState()

```
getReceivedState() => Promise<GetReceivedStateResult>
```

Get the last state that was received from the watch.

The state is persisted and can be read at any time, including after an app restart.

Only available on Android and iOS.

**Returns:** `Promise<GetReceivedStateResult>`

**Since:** 0.0.1

______________________________________________________________________

### replyToMessage(...)

```
replyToMessage(options: ReplyToMessageOptions) => Promise<void>
```

Reply to a message that was received from the watch.

This is only possible if the `messageReceived` event provided a `messageId`.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `ReplyToMessageOptions` |

**Since:** 0.0.1

______________________________________________________________________

### sendMessage(...)

```
sendMessage(options: SendMessageOptions) => Promise<SendMessageResult>
```

Send a message to the watch for immediate delivery.

The watch must be reachable, otherwise the call is rejected.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SendMessageOptions` |

**Returns:** `Promise<SendMessageResult>`

**Since:** 0.0.1

______________________________________________________________________

### transferUserInfo(...)

```
transferUserInfo(options: TransferUserInfoOptions) => Promise<void>
```

Transfer data to the watch in a queue.

In contrast to `updateState(...)`, every transfer is delivered, even if the watch is currently not reachable.

On iOS, the transfers are delivered in the order they were queued. On Android, there is no ordering guarantee between transfers.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `TransferUserInfoOptions` |

**Since:** 0.0.1

______________________________________________________________________

### updateState(...)

```
updateState(options: UpdateStateOptions) => Promise<void>
```

Update the state that is delivered to the watch.

Only the latest state is delivered. If the watch is currently not reachable, the state is delivered as soon as it is reachable again.

Only available on Android and iOS.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UpdateStateOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('messageReceived', ...)

```
addListener(eventName: 'messageReceived', listenerFunc: (event: MessageReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a message from the watch is received.

Only available on Android and iOS.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'messageReceived'`                     |
| **`listenerFunc`** | `(event: MessageReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('reachabilityChange', ...)

```
addListener(eventName: 'reachabilityChange', listenerFunc: (event: ReachabilityChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the reachability of the watch changes.

Only available on Android and iOS.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'reachabilityChange'`                     |
| **`listenerFunc`** | `(event: ReachabilityChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('stateReceived', ...)

```
addListener(eventName: 'stateReceived', listenerFunc: (event: StateReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a state update from the watch is received.

Only available on Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'stateReceived'`                     |
| **`listenerFunc`** | `(event: StateReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('userInfoReceived', ...)

```
addListener(eventName: 'userInfoReceived', listenerFunc: (event: UserInfoReceivedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a user info transfer from the watch is received.

Only available on Android and iOS.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'userInfoReceived'`                     |
| **`listenerFunc`** | `(event: UserInfoReceivedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### GetConnectionInfoResult

| Prop                    | Type      | Description                                                                                                                                                                                                         | Since                                                                                                                                                                             |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`paired`**            | \`boolean | null\`                                                                                                                                                                                                              | Whether or not a watch is paired with the device. On Android, this value is always `null` since the platform does not provide this information.                                   |
| **`reachable`**         | `boolean` | Whether or not the watch is currently reachable for immediate message delivery. On Android, this requires that the watch app is installed and has declared the configured capability (default: `capawesome_watch`). | 0.0.1                                                                                                                                                                             |
| **`watchAppInstalled`** | \`boolean | null\`                                                                                                                                                                                                              | Whether or not the watch app is installed on the watch. On Android, this is derived from the configured capability (default: `capawesome_watch`) that the watch app must declare. |

#### GetReceivedStateResult

| Prop       | Type                       | Description | Since                                                                                        |
| ---------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
| **`data`** | \`Record\<string, unknown> | null\`      | The last state that was received from the watch or `null` if no state has been received yet. |

#### ReplyToMessageOptions

| Prop            | Type                      | Description                                                                            | Since |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------- | ----- |
| **`data`**      | `Record<string, unknown>` | The data to send as reply. Must be JSON-serializable. `null` values are not supported. | 0.0.1 |
| **`messageId`** | `string`                  | The identifier of the message to reply to as provided by the `messageReceived` event.  | 0.0.1 |

#### SendMessageResult

| Prop        | Type                       | Description | Since                                                                          |
| ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------ |
| **`reply`** | \`Record\<string, unknown> | null\`      | The reply that was received from the watch or `null` if no reply was expected. |

#### SendMessageOptions

| Prop               | Type                      | Description                                                                                                                  | Default | Since |
| ------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`data`**         | `Record<string, unknown>` | The data to send. Must be JSON-serializable. `null` values are not supported.                                                |         | 0.0.1 |
| **`expectsReply`** | `boolean`                 | Whether or not the watch is expected to reply to the message. If `true`, the call resolves as soon as the watch has replied. | `false` | 0.0.1 |

#### TransferUserInfoOptions

| Prop       | Type                      | Description                                                                       | Since |
| ---------- | ------------------------- | --------------------------------------------------------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data to transfer. Must be JSON-serializable. `null` values are not supported. | 0.0.1 |

#### UpdateStateOptions

| Prop       | Type                      | Description                                                                                          | Since |
| ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data to deliver as the latest state. Must be JSON-serializable. `null` values are not supported. | 0.0.1 |

#### PluginListenerHandle

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

#### MessageReceivedEvent

| Prop            | Type                      | Description                 | Since                                                                                                                              |
| --------------- | ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **`data`**      | `Record<string, unknown>` | The data that was received. | 0.0.1                                                                                                                              |
| **`messageId`** | \`string                  | null\`                      | The identifier of the message if the watch expects a reply. In this case, you should reply using the `replyToMessage(...)` method. |

#### ReachabilityChangeEvent

| Prop            | Type      | Description                                                                     | Since |
| --------------- | --------- | ------------------------------------------------------------------------------- | ----- |
| **`reachable`** | `boolean` | Whether or not the watch is currently reachable for immediate message delivery. | 0.0.1 |

#### StateReceivedEvent

| Prop       | Type                      | Description                 | Since |
| ---------- | ------------------------- | --------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data that was received. | 0.0.1 |

#### UserInfoReceivedEvent

| Prop       | Type                      | Description                 | Since |
| ---------- | ------------------------- | --------------------------- | ----- |
| **`data`** | `Record<string, unknown>` | The data that was received. | 0.0.1 |

## Communication Channels

The plugin exposes the three communication channels of the platforms with honest, platform-true semantics:

| Method                  | Semantics                         | iOS                        | Android                  | Guarantee                                      |
| ----------------------- | --------------------------------- | -------------------------- | ------------------------ | ---------------------------------------------- |
| `sendMessage(...)`      | Live, interactive, optional reply | `WCSession.sendMessage`    | `MessageClient`          | Requires reachability, not queued              |
| `updateState(...)`      | Latest state wins                 | `updateApplicationContext` | `DataItem` (fixed path)  | Replaces undelivered state, survives restarts  |
| `transferUserInfo(...)` | Queued, all delivered             | `transferUserInfo`         | `DataItem` (unique path) | Queued until delivered, even across relaunches |

The payload of all channels is limited to about 100 KB by the operating systems.

## Platform Behavior

The two platform stacks behave differently in some aspects. The plugin does not paper over these differences:

| Behavior                       | iOS                                                                | Android                                                                         |
| ------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Watch → phone `sendMessage`    | Wakes the phone app in the background if it is not running.        | Starts the plugin's `WearableListenerService`; the event is queued for JS.      |
| Phone → watch `sendMessage`    | Does **not** launch the watch app. The watch app must be running.  | Does **not** launch the watch app. The watch app's listener service is started. |
| `paired` / `watchAppInstalled` | Provided by the system.                                            | `paired` is always `null`; `watchAppInstalled` is derived from the capability.  |
| State persistence              | The latest received state is persisted by the system.              | The state is persisted and replicated by the Data Layer.                        |
| Identical state updates        | May not be redelivered if the data did not change.                 | May not be redelivered if the data did not change.                              |
| Queued transfers               | Delivered in the order they were queued.                           | No ordering guarantee. The 100 most recent undelivered transfers are kept.      |
| Payload types                  | Must be property list compatible; `null` values are not supported. | Any JSON-serializable data.                                                     |

**Note**: A Wear OS watch that is paired to an iPhone is **not** supported. The Google Play services Data Layer only works between an Android phone and a Wear OS watch.

## FAQ

### How is this plugin different from other similar plugins?

It is a single, unified bridge between your Capacitor app and native Apple Watch and Wear OS apps, exposing the three platform channels honestly — live messages with optional replies, latest-wins state sync, and queued transfers for guaranteed delivery — plus reachability info and background reception of data that arrives while your app is closed. It even ships native watch-side SDKs for watchOS and Wear OS and needs no `AppDelegate` or `MainActivity` changes, so you build your watch UI natively and wire up communication with minimal boilerplate. Everything is fully typed, actively maintained against the latest OS and Capacitor versions and backed by dedicated support.

### Do I need to modify my AppDelegate on iOS?

No. The plugin activates the `WCSession` when it is loaded and handles all session delegate callbacks internally, including background deliveries that launch the app.

### What happens to data that arrives while my app is closed?

On Android, the plugin's manifest-registered `WearableListenerService` receives the data even while your app is not running and persists it, so the events are replayed as soon as your listeners are registered, even after an app restart. On iOS, a message from the watch wakes your app in the background and the events are retained in memory until your listeners are registered. Events that have not been consumed are therefore lost on iOS if the app is terminated in the meantime.

### Can my Wear OS watch app communicate with an iPhone app?

No. The Google Play services Data Layer only works between an Android phone and a Wear OS watch. Likewise, an Apple Watch can only communicate with an iPhone. This is a platform limitation, not a plugin limitation.

### Why does `sendMessage(...)` reject with `WATCH_NOT_REACHABLE`?

The message channel is a live channel and requires the watch to be reachable. On Android, also make sure that your watch app declares the `capawesome_watch` capability (see the Wear OS setup). If you need guaranteed delivery, use `transferUserInfo(...)` instead.

### Does the watch app UI come from the plugin?

No, and that is deliberate. You build your watch UI natively (e.g. with SwiftUI or Jetpack Compose) with the full power of the platform, and use the shipped watch-side SDKs to communicate with your Capacitor app.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Health](https://capawesome.io/docs/sdks/capacitor/health/): Read health and fitness data that pairs well with a watch experience.
- [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/): Track the device location in the background.
- [Geofences](https://capawesome.io/docs/sdks/capacitor/geofences/): Monitor geographic regions, even when the app is closed.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/watch/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/watch/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/watch/LICENSE).

# Capacitor Wifi Plugin

Capacitor plugin to manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks. Supports both Android and iOS.[1](#fn:1)[2](#fn:2)

## Features

The Capacitor Wifi plugin is one of the most complete Wi-Fi management solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 🌐 **Network Management**: Add, connect and disconnect networks.
- 🔍 **Network Scan**: Perform scans for available networks.
- 📟 **Device Info**: Retrieve essential device information like IP address.
- 🤝 **Compatibility**: Works alongside the [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/), [Network](https://capawesome.io/docs/sdks/capacitor/network/) and [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/) plugins.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Wifi plugin is typically used whenever an app needs to interact with Wi-Fi networks, for example:

- **IoT device onboarding**: Connect to the access point of a smart home device, camera, or other IoT hardware to configure it.
- **Guest Wi-Fi access**: Add a Wi-Fi network to the device's list of known networks via a system dialog, for example in hotel or event apps.
- **Network diagnostics**: Display the SSID, IP address, and signal strength (RSSI) of the current network.
- **Network discovery**: Scan for nearby Wi-Fi networks and present them to the user, for example in a setup wizard.

## Compatibility

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

## Demo

| Android | iOS |
| ------- | --- |
|         |     |

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-wifi` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-wifi
npx cap sync
```

### Android

#### Permissions

This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag:

```
<!-- Required if you want retrieve information about nearby Wi-Fi networks. -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
```

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Entitlements

Ensure `Access Wi-Fi Information` and `Hotspot` capabilities have been enabled in your application in Xcode. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information.

#### Privacy Descriptions

Add the `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription` keys to the `ios/App/App/Info.plist` file, which tells the user why your app is requesting location information:

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to request Wi-Fi information.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location to request Wi-Fi information.</string>
```

## Configuration

| Prop                 | Type      | Description                                                                                                                                             | Default | Since |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`useWifiManager`** | `boolean` | Whether or not to use the **deprecated** `WifiManager` API for connecting to Wi-Fi networks using the `connect(...)` method. Only available on Android. | `false` | 6.3.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "Wifi": {
      "useWifiManager": undefined
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capawesome-team/capacitor-wifi" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Wifi: {
      useWifiManager: undefined,
    },
  },
};

export default config;
```

## Usage

The following examples show how to connect to and disconnect from a Wi-Fi network, scan for available networks, read information about the current network, and check whether Wi-Fi is enabled.

### Connect to a Wi-Fi network

Connect to a network by providing its SSID and password. On Android, the network will not be added to the device's list of known networks and no traffic will be routed through it; use `addNetwork(...)` instead if you want that. On iOS, `connect(...)` behaves the same as `addNetwork(...)`. Only available on Android and iOS:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const connect = async () => {
    await Wifi.connect({
        ssid: 'MyNetwork',
        password: 'MyPassword',
        isHiddenSsid: false
    });
}
```

### Disconnect from a Wi-Fi network

On iOS, you can only disconnect from networks that you connected to using the plugin. This also removes the network from the list of known networks. Only available on Android and iOS:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const disconnect = async () => {
    await Wifi.disconnect();
}
```

### Scan for available Wi-Fi networks

Start a scan with `startScan()` and retrieve the results with `getAvailableNetworks()`. You can also listen for the `networksScanned` event to be notified when the scan results are available. Note that scan requests may be throttled if you scan too often. Only available on Android:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const startScan = async () => {
    await Wifi.startScan();
}

const getAvailableNetworks = async () => {
    const result = await Wifi.getAvailableNetworks();
    return result.networks;
}
```

### Get information about the current network

Retrieve the SSID and IP address of the current network on Android and iOS. The signal strength (RSSI) is only available on Android:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const getSsid = async () => {
    const result = await Wifi.getSsid();
    return result.ssid;
}

const getIpAddress = async () => {
    const result = await Wifi.getIpAddress();
    return result.address;
}

const getRssi = async () => {
    const result = await Wifi.getRssi();
    return result.rssi;
}
```

### Check if Wi-Fi is enabled

Check whether Wi-Fi is turned on. Only available on Android:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const isEnabled = async () => {
    const result = await Wifi.isEnabled();
    return result.enabled;
}
```

## API

- [`addNetwork(...)`](#addnetwork)
- [`connect(...)`](#connect)
- [`disconnect(...)`](#disconnect)
- [`getAvailableNetworks()`](#getavailablenetworks)
- [`getIpAddress()`](#getipaddress)
- [`getRssi()`](#getrssi)
- [`getSsid()`](#getssid)
- [`isEnabled()`](#isenabled)
- [`startScan()`](#startscan)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions(...)`](#requestpermissions)
- [`addListener('networksScanned', ...)`](#addlistenernetworksscanned-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### addNetwork(...)

```
addNetwork(options: AddNetworkOptions) => Promise<void>
```

Show a system dialog to add a Wi-Fi network to the device.

If the user accepts, the network will be added to the device's list of known networks and the traffic will be routed through it.

Only available on Android (SDK 30+) and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `AddNetworkOptions` |

**Since:** 7.1.0

______________________________________________________________________

### connect(...)

```
connect(options: ConnectOptions) => Promise<void>
```

Connect to a Wi-Fi network.

On **Android**, the network will NOT be added to the device's list of known networks and NO traffic will be routed through it. If you want to route traffic through the network, use `addNetwork(...)` instead.

On **iOS**, this is the same as `addNetwork()`.

Only available on Android and iOS.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `ConnectOptions` |

**Since:** 6.0.0

______________________________________________________________________

### disconnect(...)

```
disconnect(options?: DisconnectOptions | undefined) => Promise<void>
```

Disconnect from a Wi-Fi network.

On **iOS**, you can only disconnect from networks that you connected to using the plugin. This also removes the Wi-Fi network from the list of known networks.

Only available on Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DisconnectOptions` |

**Since:** 6.0.0

______________________________________________________________________

### getAvailableNetworks()

```
getAvailableNetworks() => Promise<GetAvailableNetworksResult>
```

Get a list of Wi-Fi networks found during the last scan.

The returned networks are the most recently updated results, which may be from a previous scan if your current scan has not completed or succeeded.

Only available on Android.

**Returns:** `Promise<GetAvailableNetworksResult>`

**Since:** 6.0.0

______________________________________________________________________

### getIpAddress()

```
getIpAddress() => Promise<GetIpAddressResult>
```

Get the current IP address of the device.

Only available on Android and iOS.

**Returns:** `Promise<GetIpAddressResult>`

**Since:** 6.0.0

______________________________________________________________________

### getRssi()

```
getRssi() => Promise<GetRssiResult>
```

Get the received signal strength indicator (RSSI) of the current network in dBm.

Only available on Android.

**Returns:** `Promise<GetRssiResult>`

**Since:** 6.0.0

______________________________________________________________________

### getSsid()

```
getSsid() => Promise<GetSsidResult>
```

Get the service set identifier (SSID) of the current network.

Only available on Android and iOS.

**Returns:** `Promise<GetSsidResult>`

**Since:** 6.0.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Check if Wi-Fi is enabled.

Only available on Android.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 6.0.0

______________________________________________________________________

### startScan()

```
startScan() => Promise<void>
```

Start a scan for Wi-Fi networks.

This call may fail for any of the following reasons:

- Scan requests may be throttled because of too many scans in a short time.
- The device is idle and scanning is disabled.
- Wi-Fi hardware reports a scan failure.

Only available on Android.

**Since:** 6.0.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permissions for the plugin.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### requestPermissions(...)

```
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>
```

Request permissions for the plugin.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `RequestPermissionsOptions` |

**Returns:** `Promise<PermissionStatus>`

**Since:** 6.0.0

______________________________________________________________________

### addListener('networksScanned', ...)

```
addListener(eventName: 'networksScanned', listenerFunc: (event: NetworksScannedEvent) => void) => Promise<PluginListenerHandle>
```

Called when the scan results are available.

Only available on Android.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'networksScanned'`                     |
| **`listenerFunc`** | `(event: NetworksScannedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.0.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### AddNetworkOptions

| Prop               | Type                      | Description                                                   | Default                                                                                                                                                                                                                   | Since                     |
| ------------------ | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| **`ssid`**         | `string`                  | The SSID of the network to add.                               |                                                                                                                                                                                                                           | 7.1.0                     |
| **`isHiddenSsid`** | `boolean`                 | Whether or not the SSID is hidden. Only available on Android. | `false`                                                                                                                                                                                                                   | 6.0.0                     |
| **`password`**     | `string`                  | The password of the network to add.                           |                                                                                                                                                                                                                           | 7.1.0                     |
| **`securityType`** | \`NetworkSecurityType.PSK | NetworkSecurityType.SAE\`                                     | The security type of the network to add. Use [`NetworkSecurityType.PSK`](#networksecuritytype) for WPA/WPA2 networks. Use [`NetworkSecurityType.SAE`](#networksecuritytype) for WPA3 networks. Only available on Android. | `NetworkSecurityType.PSK` |

#### ConnectOptions

| Prop               | Type      | Description                                                   | Default | Since |
| ------------------ | --------- | ------------------------------------------------------------- | ------- | ----- |
| **`ssid`**         | `string`  | The SSID of the network to connect to.                        |         | 6.0.0 |
| **`isHiddenSsid`** | `boolean` | Whether or not the SSID is hidden. Only available on Android. | `false` | 6.0.0 |
| **`password`**     | `string`  | The password of the network to connect to.                    |         | 6.0.0 |

#### DisconnectOptions

| Prop       | Type     | Description                                                                                                                              | Since |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`ssid`** | `string` | The SSID of the network to disconnect from. If not provided, the device will disconnect from the current network. Only available on iOS. | 6.0.0 |

#### GetAvailableNetworksResult

| Prop           | Type        | Description                                            | Since |
| -------------- | ----------- | ------------------------------------------------------ | ----- |
| **`networks`** | `Network[]` | The list of Wi-Fi networks found during the last scan. | 6.0.0 |

#### Network

| Prop                | Type                    | Description                                                                            | Since |
| ------------------- | ----------------------- | -------------------------------------------------------------------------------------- | ----- |
| **`rssi`**          | `number`                | The received signal strength indicator (RSSI) of the network in dBm.                   | 6.1.0 |
| **`securityTypes`** | `NetworkSecurityType[]` | The service set identifier (SSID) of the network. Only available on Android (SDK 33+). | 6.1.0 |
| **`ssid`**          | `string`                | The service set identifier (SSID) of the network.                                      | 6.0.0 |

#### GetIpAddressResult

| Prop          | Type     | Description                   | Since |
| ------------- | -------- | ----------------------------- | ----- |
| **`address`** | `string` | The IP address of the device. | 6.0.0 |

#### GetRssiResult

| Prop       | Type     | Description                                                                  | Since |
| ---------- | -------- | ---------------------------------------------------------------------------- | ----- |
| **`rssi`** | `number` | The received signal strength indicator (RSSI) of the current network in dBm. | 6.0.0 |

#### GetSsidResult

| Prop       | Type     | Description                                                                                                                                                                                                        | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`ssid`** | `string` | The service set identifier (SSID) of the current network. On **iOS 14+**, the SSID can only be retrieved if the network was connected to using the plugin or if the app has permission to access precise location. | 6.0.0 |

#### IsEnabledResult

| Prop          | Type      | Description                      | Since |
| ------------- | --------- | -------------------------------- | ----- |
| **`enabled`** | `boolean` | Whether or not Wi-Fi is enabled. | 6.0.0 |

#### PermissionStatus

| Prop           | Type              | Since |
| -------------- | ----------------- | ----- |
| **`location`** | `PermissionState` | 6.0.0 |

#### RequestPermissionsOptions

| Prop              | Type           | Description                 | Default        | Since |
| ----------------- | -------------- | --------------------------- | -------------- | ----- |
| **`permissions`** | `'location'[]` | The permissions to request. | `["location"]` | 6.0.0 |

#### PluginListenerHandle

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

#### NetworksScannedEvent

| Prop           | Type        | Description                                       | Since |
| -------------- | ----------- | ------------------------------------------------- | ----- |
| **`networks`** | `Network[]` | The list of Wi-Fi networks found during the scan. | 6.0.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### PermissionType

`'location'`

### Enums

#### NetworkSecurityType

| Members                           | Value | Description                                                                                | Since |
| --------------------------------- | ----- | ------------------------------------------------------------------------------------------ | ----- |
| **`UNKNOWN`**                     | `-1`  | Unknown security type.                                                                     | 6.1.0 |
| **`OPEN`**                        | `0`   | Open network.                                                                              | 6.1.0 |
| **`WEP`**                         | `1`   | WEP network.                                                                               | 6.1.0 |
| **`PSK`**                         | `2`   | PSK (Pre-Shared Key) network. This includes WPA/WPA2/WPA3-Personal networks.               | 6.1.0 |
| **`EAP`**                         | `3`   | EAP (Extensible Authentication Protocol) network.                                          | 6.1.0 |
| **`SAE`**                         | `4`   | SAE (Simultaneous Authentication of Equals) network.                                       | 6.1.0 |
| **`EAP_WPA3_ENTERPRISE_192_BIT`** | `5`   | WPA3-Enterprise in 192-bit security network.                                               | 6.1.0 |
| **`OWE`**                         | `6`   | OWE network.                                                                               | 6.1.0 |
| **`WAPI_PSK`**                    | `7`   | WAPI PSK network.                                                                          | 6.1.0 |
| **`WAPI_CERT`**                   | `8`   | WAPI Certificate network.                                                                  | 6.1.0 |
| **`WPA3_ENTERPRISE`**             | `9`   | WPA3-Enterprise network.                                                                   | 6.1.0 |
| **`OSEN`**                        | `10`  | OSEN network.                                                                              | 6.1.0 |
| **`PASSPOINT_R1_R2`**             | `11`  | Passpoint R1/R2 network, where TKIP and WEP are not allowed.                               | 6.1.0 |
| **`PASSPOINT_R3`**                | `12`  | Passpoint R3 network, where TKIP and WEP are not allowed, and PMF must be set to Required. | 6.1.0 |
| **`DPP`**                         | `13`  | Easy Connect (DPP) network.                                                                | 6.1.0 |

## FAQ

### Why is the SSID not returned on iOS?

On iOS 14 and later, the SSID can only be retrieved if the network was connected to using the plugin or if the app has permission to access precise location. Make sure the `Access Wi-Fi Information` capability and the location privacy descriptions are set up as described in the [Installation](#installation) section, and request the location permission at runtime using `requestPermissions(...)`.

### What is the difference between `connect` and `addNetwork`?

On Android, `connect(...)` establishes a connection without adding the network to the device's list of known networks and without routing traffic through it. `addNetwork(...)` shows a system dialog and, if the user accepts, adds the network to the list of known networks and routes traffic through it. On iOS, both methods behave identically. Note that `addNetwork(...)` requires Android SDK 30 or later.

### Why does `startScan` fail on Android?

The call may fail because scan requests are throttled after too many scans in a short time, because the device is idle and scanning is disabled, or because the Wi-Fi hardware reports a scan failure. In that case, you can still call `getAvailableNetworks()` to get the most recently updated results from a previous scan.

### What permissions does this plugin require?

On Android, the `ACCESS_FINE_LOCATION` permission is required if you want to retrieve information about nearby Wi-Fi networks. On iOS, the `Access Wi-Fi Information` and `Hotspot` capabilities must be enabled and the location privacy descriptions must be added to your `Info.plist` file. You can check and request the location permission at runtime using `checkPermissions()` and `requestPermissions(...)`. See [Installation](#installation) for details.

### Does this plugin work on the Web?

No, the plugin only supports Android and iOS, since web browsers do not expose APIs for managing Wi-Fi connectivity. The supported platforms for each method are documented in the [API](#api) section.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with Bluetooth Low Energy devices in the central and peripheral role.
- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information such as the connection type and status.
- [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/): Read, write, and emulate NFC tags.
- [SIM](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/wifi/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/wifi/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/wifi/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Wi-Fi Alliance or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `Wi-Fi` is a registered trademark of Wi-Fi Alliance. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor YouTube Player Plugin

Unofficial Capacitor plugin to embed and control [YouTube](https://www.youtube.com/) players on Android, iOS, and Web.[1](#fn:1)

## Features

The Capacitor YouTube Player plugin embeds YouTube videos as inline, frame-positioned players in your Capacitor app. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
- 🎞️ **Inline Playback**: Embed players inline on all platforms, including iOS.
- 🧩 **Multi-Instance**: Create and control multiple players at the same time by ID.
- 📐 **Frame Positioning**: Position and resize players with CSS pixel frames and keep them in sync with your layout.
- 🎛️ **Playback Controls**: Load, cue, play, pause, seek, mute, volume, and playback rate.
- 📡 **Typed Events**: Listen for ready, state, time, rate, error, and fullscreen events with typed listeners.
- 📜 **Terms Compliant**: Built on the official YouTube IFrame Player API with TOS-compliant plumbing (see [YouTube Terms of Service](#youtube-terms-of-service)).
- 🤝 **Compatibility**: Works alongside the [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/) and [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The YouTube Player plugin is typically used wherever you want to embed YouTube videos in your app, for example:

- **Media apps**: Embed trailers, music videos, or episodes inline in your content.
- **Onboarding & help**: Show tutorial and how-to videos directly in your app.
- **News & blogs**: Render YouTube embeds in articles with native playback performance.
- **Education**: Build course screens with multiple video lessons on one page.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-youtube-player` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome/capacitor-youtube-player
npx cap sync
```

### Android

On Android, the plugin uses the [android-youtube-player](https://github.com/PierfrancescoSoffritti/android-youtube-player) library, an open-source wrapper around the official YouTube IFrame Player API.

#### Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

- `$androidYoutubePlayerVersion` version of `com.pierfrancescosoffritti.androidyoutubeplayer:core` (default: `13.0.0`)

#### Permissions

The plugin automatically adds the `android.permission.ACCESS_NETWORK_STATE` permission to your app's manifest. It is used to recover the player when the network connection is lost and restored. No action is required on your part.

### iOS

On iOS, the plugin uses the [YoutubePlayerView](https://github.com/mukeshydv/YoutubePlayerView) library, an open-source wrapper around the official YouTube IFrame Player API. It can be integrated via Swift Package Manager or CocoaPods. No additional configuration is required.

### Web

The web implementation loads the [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) from YouTube at runtime. This requires an active network connection. If your app enforces a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), make sure to allow the YouTube domains (e.g. `https://www.youtube.com` for `script-src` and `frame-src`).

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to use the plugin.

### Create a player

Measure a placeholder element in your layout and create a player at its position:

```
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const createPlayer = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.createPlayer({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
    videoId: 'dQw4w9WgXcQ',
    options: {
      mute: true,
    },
  });
};
```

### Control playback

```
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const controlPlayback = async () => {
  await YoutubePlayer.play({ id: 'my-player' });
  await YoutubePlayer.seekTo({ id: 'my-player', seconds: 42 });
  await YoutubePlayer.setVolume({ id: 'my-player', volume: 50 });
  await YoutubePlayer.setPlaybackRate({ id: 'my-player', rate: 1.5 });
  await YoutubePlayer.pause({ id: 'my-player' });
};
```

### Listen for events

```
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const addListeners = async () => {
  await YoutubePlayer.addListener('playerReady', event => {
    console.log('Player ready:', event.id);
  });
  await YoutubePlayer.addListener('playerStateChange', event => {
    console.log('Player state:', event.id, event.state);
  });
  await YoutubePlayer.addListener('playerError', event => {
    console.error('Player error:', event.id, event.code);
  });
};
```

### Remove a player

```
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const removePlayer = async () => {
  await YoutubePlayer.removePlayer({ id: 'my-player' });
};
```

## API

- [`createPlayer(...)`](#createplayer)
- [`cueVideo(...)`](#cuevideo)
- [`getCurrentTime(...)`](#getcurrenttime)
- [`getDuration(...)`](#getduration)
- [`loadVideo(...)`](#loadvideo)
- [`mute(...)`](#mute)
- [`pause(...)`](#pause)
- [`play(...)`](#play)
- [`removePlayer(...)`](#removeplayer)
- [`seekTo(...)`](#seekto)
- [`setPlaybackRate(...)`](#setplaybackrate)
- [`setPlayerFrame(...)`](#setplayerframe)
- [`setVolume(...)`](#setvolume)
- [`unmute(...)`](#unmute)
- [`addListener('currentTimeChange', ...)`](#addlistenercurrenttimechange-)
- [`addListener('fullscreenChange', ...)`](#addlistenerfullscreenchange-)
- [`addListener('playbackRateChange', ...)`](#addlistenerplaybackratechange-)
- [`addListener('playerError', ...)`](#addlistenerplayererror-)
- [`addListener('playerReady', ...)`](#addlistenerplayerready-)
- [`addListener('playerStateChange', ...)`](#addlistenerplayerstatechange-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### createPlayer(...)

```
createPlayer(options: CreatePlayerOptions) => Promise<CreatePlayerResult>
```

Create a new YouTube player.

On Android and iOS, the player is rendered as a native view that is positioned above the web view at the given frame. The frame is not scrolled with the web content. Use `setPlayerFrame(...)` to keep the frame in sync with your layout (see the README for a recipe).

The player must be at least 200×200 CSS pixels, as required by the [YouTube Terms of Service](https://developers.google.com/youtube/terms/required-minimum-functionality#embedded-player-size).

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `CreatePlayerOptions` |

**Returns:** `Promise<CreatePlayerResult>`

**Since:** 0.1.0

______________________________________________________________________

### cueVideo(...)

```
cueVideo(options: CueVideoOptions) => Promise<void>
```

Load a video into the player without starting playback.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `CueVideoOptions` |

**Since:** 0.1.0

______________________________________________________________________

### getCurrentTime(...)

```
getCurrentTime(options: GetCurrentTimeOptions) => Promise<GetCurrentTimeResult>
```

Get the current playback time of the player.

On Android, the value is answered from the most recent value pushed by the player (updated multiple times per second during playback).

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetCurrentTimeOptions` |

**Returns:** `Promise<GetCurrentTimeResult>`

**Since:** 0.1.0

______________________________________________________________________

### getDuration(...)

```
getDuration(options: GetDurationOptions) => Promise<GetDurationResult>
```

Get the duration of the currently loaded video.

On Android, the value is answered from the most recent value pushed by the player.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetDurationOptions` |

**Returns:** `Promise<GetDurationResult>`

**Since:** 0.1.0

______________________________________________________________________

### loadVideo(...)

```
loadVideo(options: LoadVideoOptions) => Promise<void>
```

Load a video into the player and start playback.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `LoadVideoOptions` |

**Since:** 0.1.0

______________________________________________________________________

### mute(...)

```
mute(options: MuteOptions) => Promise<void>
```

Mute the player.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `MuteOptions` |

**Since:** 0.1.0

______________________________________________________________________

### pause(...)

```
pause(options: PauseOptions) => Promise<void>
```

Pause playback.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `PauseOptions` |

**Since:** 0.1.0

______________________________________________________________________

### play(...)

```
play(options: PlayOptions) => Promise<void>
```

Start or resume playback.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `PlayOptions` |

**Since:** 0.1.0

______________________________________________________________________

### removePlayer(...)

```
removePlayer(options: RemovePlayerOptions) => Promise<void>
```

Remove the player and release all its resources.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `RemovePlayerOptions` |

**Since:** 0.1.0

______________________________________________________________________

### seekTo(...)

```
seekTo(options: SeekToOptions) => Promise<void>
```

Seek to the given time.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `SeekToOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setPlaybackRate(...)

```
setPlaybackRate(options: SetPlaybackRateOptions) => Promise<void>
```

Set the playback rate of the player.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetPlaybackRateOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setPlayerFrame(...)

```
setPlayerFrame(options: SetPlayerFrameOptions) => Promise<void>
```

Update the frame of the player.

Call this method whenever the layout changes (e.g. on scroll, resize or orientation change) to keep the player in sync with your layout.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SetPlayerFrameOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setVolume(...)

```
setVolume(options: SetVolumeOptions) => Promise<void>
```

Set the volume of the player.

On iOS, the operating system does not allow changing the volume programmatically, so this method has no effect. Use `mute()` and `unmute()` instead.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetVolumeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### unmute(...)

```
unmute(options: UnmuteOptions) => Promise<void>
```

Unmute the player.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `UnmuteOptions` |

**Since:** 0.1.0

______________________________________________________________________

### addListener('currentTimeChange', ...)

```
addListener(eventName: 'currentTimeChange', listenerFunc: (event: CurrentTimeChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the current playback time of a player changes.

The event is emitted multiple times per second during playback. The exact frequency depends on the platform.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'currentTimeChange'`                     |
| **`listenerFunc`** | `(event: CurrentTimeChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('fullscreenChange', ...)

```
addListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when a player enters or exits fullscreen.

Only available on Android and Web.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'fullscreenChange'`                     |
| **`listenerFunc`** | `(event: FullscreenChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('playbackRateChange', ...)

```
addListener(eventName: 'playbackRateChange', listenerFunc: (event: PlaybackRateChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the playback rate of a player changes.

On iOS, this event is only emitted for `setPlaybackRate(...)` calls.

| Param              | Type                                       |
| ------------------ | ------------------------------------------ |
| **`eventName`**    | `'playbackRateChange'`                     |
| **`listenerFunc`** | `(event: PlaybackRateChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('playerError', ...)

```
addListener(eventName: 'playerError', listenerFunc: (event: PlayerErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs in a player.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'playerError'`                     |
| **`listenerFunc`** | `(event: PlayerErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('playerReady', ...)

```
addListener(eventName: 'playerReady', listenerFunc: (event: PlayerReadyEvent) => void) => Promise<PluginListenerHandle>
```

Called when a player has finished loading and is ready to receive commands.

| Param              | Type                                |
| ------------------ | ----------------------------------- |
| **`eventName`**    | `'playerReady'`                     |
| **`listenerFunc`** | `(event: PlayerReadyEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('playerStateChange', ...)

```
addListener(eventName: 'playerStateChange', listenerFunc: (event: PlayerStateChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when the state of a player changes.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'playerStateChange'`                     |
| **`listenerFunc`** | `(event: PlayerStateChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CreatePlayerResult

| Prop     | Type     | Description                                  | Since |
| -------- | -------- | -------------------------------------------- | ----- |
| **`id`** | `string` | The unique identifier of the created player. | 0.1.0 |

#### CreatePlayerOptions

| Prop          | Type                     | Description                                                                                                                                                     | Since |
| ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`frame`**   | `PlayerFrame`            | The frame of the player in CSS pixels, relative to the viewport. Must be at least 200×200 CSS pixels.                                                           | 0.1.0 |
| **`id`**      | `string`                 | The unique identifier of the player. If not provided, a random identifier is generated.                                                                         | 0.1.0 |
| **`options`** | `PlayerOptions`          | The player options.                                                                                                                                             | 0.1.0 |
| **`videoId`** | `string`                 | The ID of the YouTube video to load into the player. If not provided, the player is created without a video. Load one with `loadVideo(...)` or `cueVideo(...)`. | 0.1.0 |
| **`web`**     | `CreatePlayerWebOptions` | Options that are only available on Web.                                                                                                                         | 0.1.0 |

#### PlayerFrame

The frame of a player in CSS pixels, relative to the viewport.

| Prop         | Type     | Description                                                     | Since |
| ------------ | -------- | --------------------------------------------------------------- | ----- |
| **`height`** | `number` | The height of the player in CSS pixels. Must be at least `200`. | 0.1.0 |
| **`width`**  | `number` | The width of the player in CSS pixels. Must be at least `200`.  | 0.1.0 |
| **`x`**      | `number` | The x-coordinate of the player in CSS pixels.                   | 0.1.0 |
| **`y`**      | `number` | The y-coordinate of the player in CSS pixels.                   | 0.1.0 |

#### PlayerOptions

| Prop               | Type      | Description                                                                                                                             | Default | Since |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`autoplay`**     | `boolean` | Whether the video starts playing automatically when the player is created.                                                              | `false` | 0.1.0 |
| **`ccLoadPolicy`** | `boolean` | Whether closed captions are shown by default, even if the user has turned captions off.                                                 | `false` | 0.1.0 |
| **`controls`**     | `boolean` | Whether the player controls are displayed.                                                                                              | `true`  | 0.1.0 |
| **`end`**          | `number`  | The time in seconds at which the player should stop playing the video.                                                                  |         | 0.1.0 |
| **`fullscreen`**   | `boolean` | Whether the fullscreen button is displayed. Only available on Android and Web.                                                          | `false` | 0.1.0 |
| **`ivLoadPolicy`** | `boolean` | Whether video annotations are shown by default.                                                                                         | `false` | 0.1.0 |
| **`mute`**         | `boolean` | Whether the player is muted when it is created.                                                                                         | `false` | 0.1.0 |
| **`rel`**          | `boolean` | Whether related videos from other channels are shown when playback ends. If `false`, related videos are limited to the video's channel. | `false` | 0.1.0 |
| **`start`**        | `number`  | The time in seconds from which the video should start playing.                                                                          |         | 0.1.0 |

#### CreatePlayerWebOptions

| Prop            | Type     | Description                                                                                                                                                                                                            | Since |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`elementId`** | `string` | The ID of an existing DOM element to mount the player into. If provided, the player fills this element instead of being positioned at the given frame, and `setPlayerFrame(...)` has no effect. Only available on Web. | 0.1.0 |

#### CueVideoOptions

| Prop               | Type     | Description                                                                      | Default | Since |
| ------------------ | -------- | -------------------------------------------------------------------------------- | ------- | ----- |
| **`id`**           | `string` | The unique identifier of the player.                                             |         | 0.1.0 |
| **`startSeconds`** | `number` | The time in seconds from which the video should start playing once it is played. | `0`     | 0.1.0 |
| **`videoId`**      | `string` | The ID of the YouTube video to cue.                                              |         | 0.1.0 |

#### GetCurrentTimeResult

| Prop              | Type     | Description                           | Since |
| ----------------- | -------- | ------------------------------------- | ----- |
| **`currentTime`** | `number` | The current playback time in seconds. | 0.1.0 |

#### GetCurrentTimeOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### GetDurationResult

| Prop           | Type     | Description                                                                               | Since |
| -------------- | -------- | ----------------------------------------------------------------------------------------- | ----- |
| **`duration`** | `number` | The duration of the currently loaded video in seconds. Returns `0` if no video is loaded. | 0.1.0 |

#### GetDurationOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### LoadVideoOptions

| Prop               | Type     | Description                                                    | Default | Since |
| ------------------ | -------- | -------------------------------------------------------------- | ------- | ----- |
| **`id`**           | `string` | The unique identifier of the player.                           |         | 0.1.0 |
| **`startSeconds`** | `number` | The time in seconds from which the video should start playing. | `0`     | 0.1.0 |
| **`videoId`**      | `string` | The ID of the YouTube video to load.                           |         | 0.1.0 |

#### MuteOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### PauseOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### PlayOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### RemovePlayerOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### SeekToOptions

| Prop          | Type     | Description                          | Since |
| ------------- | -------- | ------------------------------------ | ----- |
| **`id`**      | `string` | The unique identifier of the player. | 0.1.0 |
| **`seconds`** | `number` | The time in seconds to seek to.      | 0.1.0 |

#### SetPlaybackRateOptions

| Prop       | Type     | Description                                                                                 | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------- | ----- |
| **`id`**   | `string` | The unique identifier of the player.                                                        | 0.1.0 |
| **`rate`** | `number` | The playback rate. Must be one of `0.25`, `0.5`, `0.75`, `1`, `1.25`, `1.5`, `1.75` or `2`. | 0.1.0 |

#### SetPlayerFrameOptions

| Prop        | Type          | Description                                                                                               | Since |
| ----------- | ------------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`frame`** | `PlayerFrame` | The new frame of the player in CSS pixels, relative to the viewport. Must be at least 200×200 CSS pixels. | 0.1.0 |
| **`id`**    | `string`      | The unique identifier of the player.                                                                      | 0.1.0 |

#### SetVolumeOptions

| Prop         | Type     | Description                                  | Since |
| ------------ | -------- | -------------------------------------------- | ----- |
| **`id`**     | `string` | The unique identifier of the player.         | 0.1.0 |
| **`volume`** | `number` | The volume as a value between `0` and `100`. | 0.1.0 |

#### UnmuteOptions

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### PluginListenerHandle

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

#### CurrentTimeChangeEvent

| Prop              | Type     | Description                           | Since |
| ----------------- | -------- | ------------------------------------- | ----- |
| **`currentTime`** | `number` | The current playback time in seconds. | 0.1.0 |
| **`id`**          | `string` | The unique identifier of the player.  | 0.1.0 |

#### FullscreenChangeEvent

| Prop             | Type      | Description                          | Since |
| ---------------- | --------- | ------------------------------------ | ----- |
| **`fullscreen`** | `boolean` | Whether the player is in fullscreen. | 0.1.0 |
| **`id`**         | `string`  | The unique identifier of the player. | 0.1.0 |

#### PlaybackRateChangeEvent

| Prop       | Type     | Description                          | Since |
| ---------- | -------- | ------------------------------------ | ----- |
| **`id`**   | `string` | The unique identifier of the player. | 0.1.0 |
| **`rate`** | `number` | The new playback rate.               | 0.1.0 |

#### PlayerErrorEvent

| Prop       | Type              | Description                          | Since |
| ---------- | ----------------- | ------------------------------------ | ----- |
| **`code`** | `PlayerErrorCode` | The error code.                      | 0.1.0 |
| **`id`**   | `string`          | The unique identifier of the player. | 0.1.0 |

#### PlayerReadyEvent

| Prop     | Type     | Description                          | Since |
| -------- | -------- | ------------------------------------ | ----- |
| **`id`** | `string` | The unique identifier of the player. | 0.1.0 |

#### PlayerStateChangeEvent

| Prop        | Type          | Description                          | Since |
| ----------- | ------------- | ------------------------------------ | ----- |
| **`id`**    | `string`      | The unique identifier of the player. | 0.1.0 |
| **`state`** | `PlayerState` | The new state of the player.         | 0.1.0 |

### Type Aliases

#### PlayerErrorCode

The error code of a player error.

`'html5-error' | 'invalid-parameter' | 'not-embeddable' | 'unknown' | 'video-not-found'`

#### PlayerState

The state of a player.

`'buffering' | 'cued' | 'ended' | 'paused' | 'playing' | 'unstarted'`

## Frame Synchronization

On Android and iOS, the player is a native view that is rendered **above** the web view. It is not part of the DOM and therefore does not scroll or resize with your web content. Instead, you position it with CSS pixel frames and keep it in sync with your layout by calling `setPlayerFrame(...)` whenever the layout changes:

```
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const syncPlayerFrame = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.setPlayerFrame({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
  });
};

window.addEventListener('scroll', syncPlayerFrame);
window.addEventListener('resize', syncPlayerFrame);
```

If you use a framework with its own scroll container (e.g. `ion-content`), attach the listener to that container's scroll event instead. On the Web, the player is positioned with `position: fixed`, so the same synchronization code works on all platforms. Alternatively, on the Web you can mount the player into an existing DOM element using the `web.elementId` option, in which case no frame synchronization is needed.

Since the player is rendered above the web view, HTML content can never overlap the player. Keep this in mind when designing your layout (see also [YouTube Terms of Service](#youtube-terms-of-service)).

## YouTube Terms of Service

By using this plugin, you agree to the [YouTube Terms of Service](https://www.youtube.com/t/terms) and the [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/api-services-terms-of-service). The plugin is designed to make it easy to comply with the [required minimum functionality](https://developers.google.com/youtube/terms/required-minimum-functionality) for embedded players:

- **Minimum player size**: Embedded players must be at least 200×200 pixels. The plugin enforces this and rejects smaller frames with the `FRAME_INVALID` error code.
- **No background playback**: Videos must not play in the background. The plugin automatically pauses all players when the app is moved to the background.
- **No overlays**: The player (including its ads) must not be obscured by other content. Since the native player view is always rendered above the web view, HTML content cannot overlap it by design.
- **Correct origin**: The plugin sets the `origin` player parameter correctly on all platforms, which avoids embed errors (e.g. error 152/153) without any header workarounds.
- **No player modification**: The plugin embeds the official YouTube player unaltered. Your app must not modify, build upon, or block any portion or functionality of the player — including any ads it serves.
- **Branding**: If your app displays YouTube logos or other brand assets alongside the player, follow the [YouTube Branding Guidelines](https://developers.google.com/youtube/terms/branding-guidelines).

## Platform Support

Not every feature is available on all platforms. The following table lists the per-platform differences of the plugin's API:

| Feature                  | Android | iOS | Web |
| ------------------------ | ------- | --- | --- |
| Playback controls        | ✅      | ✅  | ✅  |
| `fullscreen` option      | ✅      | ❌  | ✅  |
| `fullscreenChange` event | ✅      | ❌  | ✅  |
| Native mute              | ✅      | 🔄  | ✅  |

Additional platform-specific behavior:

- **iOS mute emulation**: The iOS player library exposes no native mute API, so `mute()` is emulated by setting the volume to `0`. `unmute()` restores the last volume set via `setVolume(...)` (or `100`). If `setVolume(...)` is called while the player is muted, the volume is only applied on the next `unmute()` call.
- **iOS playback rate event**: On iOS, the `playbackRateChange` event is only emitted for `setPlaybackRate(...)` calls, since the iOS player library exposes no playback rate callback.
- **iOS error mapping**: On iOS, videos that are not allowed to be played in embedded players may be reported with the error code `unknown` instead of `not-embeddable`, due to the error mapping of the iOS player library.
- **Android getters**: On Android, `getCurrentTime(...)` and `getDuration(...)` are answered from the most recent values pushed by the player, which are updated multiple times per second during playback.
- **`currentTimeChange` frequency**: The event is emitted about 10 times per second on Android and about twice per second on iOS and Web.

## FAQ

### How is this plugin different from other similar plugins?

This plugin can render multiple native player instances at once, each positioned to an exact frame that you keep in sync with your layout. It exposes a full, strongly typed event set on Android, iOS, and Web, and embeds the official YouTube player unaltered. It is built to comply with the behaviors the YouTube Terms of Service require — a minimum player size, no background playback, nothing drawn over the player, and a correct origin — so you stay compliant by default. It is actively maintained and backed by dedicated support.

### Why is my frame rejected with `FRAME_INVALID`?

Embedded YouTube players must be at least 200×200 CSS pixels, as required by the YouTube Terms of Service. Make sure the `width` and `height` of your frame are at least `200`.

### Why does the player not scroll with my content?

On Android and iOS, the player is a native view rendered above the web view and is not part of the DOM. Use `setPlayerFrame(...)` to keep it in sync with your layout (see [Frame Synchronization](#frame-synchronization)).

### Can I display HTML content above the player?

No. The native player view is always rendered above the web view. This is also a requirement of the YouTube Terms of Service, which prohibit obscuring the player.

### Does playback continue in the background?

No. The YouTube Terms of Service prohibit background playback, so the plugin automatically pauses all players when the app is moved to the background.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons.
- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation, for example to allow landscape playback.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or YouTube LLC or any of their affiliates or subsidiaries. "YouTube" is a trademark of Google LLC. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Zeroconf Plugin

Capacitor plugin to discover and advertise services on the local network using mDNS/DNS-SD (Zeroconf) on Android and iOS. Compatible with services published by Apple Bonjour and Avahi.[1](#fn:1)[2](#fn:2)

## Features

The Capacitor Zeroconf plugin lets your app find other devices on the same network and make itself discoverable, without the user ever typing in an IP address. Here are some of the key features:

- 🔍 **Service Discovery**: Discover services of a given type on the local network, with multiple discoveries running at the same time.
- 📡 **Service Advertising**: Advertise your own service on the local network, including its TXT record.
- 🧭 **Modern OS APIs**: Built on `NsdManager` on Android and the system DNS-SD API on iOS, so there is no bundled mDNS stack and no raw socket handling.
- 🌐 **Addresses & Ports**: Resolve a service to its hostname, port, IPv4 and IPv6 addresses, instead of only its name.
- 🎯 **Explicit Resolution**: Resolve services automatically or on demand, so your app does not resolve every service it sees.
- 🔒 **Permissions**: First-class support for the local network permission, including the system service picker on Android that needs no permission at all.
- ⚠️ **Actionable Errors**: The iOS configuration is validated at runtime, so a missing `Info.plist` entry becomes a clear error instead of an empty result.
- 🤝 **Compatibility**: Works alongside the [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/) and [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/) plugins.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!

## Use Cases

The Zeroconf plugin is typically used whenever an app needs to talk to another device on the same network, for example:

- **IoT and smart home**: Find cameras, sensors, or controllers on the network and connect to them by IP address and port.
- **Printing**: Discover network printers and read their capabilities from the TXT record before sending a print job.
- **Local servers**: Let the app find an on-premise or desktop server without asking the user to enter an IP address that may change.
- **Point of sale and medical devices**: Connect to local hardware in environments that have no internet connection at all.
- **Peer-to-peer features**: Advertise the app itself as a service so that other devices running your app can discover it.
- **Media**: Find media servers and streaming targets on the network.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.x.x          | >=8.x.x           | Active support |

## Testing

Service discovery and advertising can only be tested on **real devices** that are connected to the **same network**:

- The **Android emulator** does not support multicast traffic, so mDNS does not work there at all. No services are found and advertised services are invisible to other devices.
- The **iOS Simulator** does not enforce local network privacy. A setup that works in the simulator can still fail silently on a device, so always verify the `Info.plist` configuration (see [iOS](#ios)) on a physical device.
- Many guest and enterprise networks block multicast traffic or isolate clients from each other. If nothing is found, cross-check with a desktop tool such as `dns-sd -B _http._tcp` on macOS or `avahi-browse -a` on Linux.

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-zeroconf` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-zeroconf
npx cap sync
```

### Android

#### Permissions

No permission is required today. The plugin already declares the permissions it needs in its manifest, so there is nothing to add to your `AndroidManifest.xml`.

Starting with **Android 17 (API level 37)**, access to the local network is permission-gated. The required `ACCESS_LOCAL_NETWORK` permission is declared by the plugin automatically, so you only have to request it at runtime (see [Check and request permissions](#check-and-request-permissions)) once your app targets SDK 37 or newer. The permission exists on Android 16 (API level 36) and newer. On older versions, `checkPermissions()` and `requestPermissions()` always report `granted`.

Alternatively, set `androidUsePicker` to `true` in `startDiscovery(...)`. The operating system then displays a service picker and delivers only the service that the user selected, **without requiring any permission at all**. This option requires Android 17 (API level 37) or newer and is ignored on iOS.

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

### iOS

#### Privacy Descriptions

Add the `NSLocalNetworkUsageDescription` key **and** an `NSBonjourServices` array to the `ios/App/App/Info.plist` file. **Both are required.** `NSLocalNetworkUsageDescription` tells the user why your app needs access to the local network, and `NSBonjourServices` is a static allow list of the service types that your app is permitted to use:

```
<key>NSLocalNetworkUsageDescription</key>
<string>The app needs access to the local network to find nearby devices.</string>
<key>NSBonjourServices</key>
<array>
  <string>_http._tcp</string>
  <string>_ipp._tcp</string>
</array>
```

Add one `<string>` entry for **every** service type that your app uses, for discovery as well as for advertising. Wildcards are not supported, so the types must be known at build time.

If a key is missing or a service type is not listed, iOS fails **silently**: no services are discovered, advertised services never become visible on the network, and the operating system reports no error whatsoever. To prevent that, the plugin reads the `Info.plist` at runtime and rejects `startDiscovery(...)`, `startAdvertising(...)` and `requestPermissions(...)` with an error message that names the exact entry to add.

#### Entitlements

The `com.apple.developer.networking.multicast` entitlement is **not** required for normal use and should not be requested. It is only needed if your app has to browse for service types that are not known at build time and therefore cannot be listed in `NSBonjourServices`. The entitlement must be requested from Apple; approval is at Apple’s discretion, may take some time and is not guaranteed.

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to discover, resolve and advertise services, and how to check and request permissions.

### Discover services

Start a discovery for a service type and stop it again once it is no longer needed. Multiple discoveries can run at the same time, each identified by the returned `id`. Only available on Android and iOS:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const startDiscovery = async () => {
  const { id } = await Zeroconf.startDiscovery({
    type: '_http._tcp',
  });
  return id;
};

const stopDiscovery = async (id: string) => {
  await Zeroconf.stopDiscoveryById({ id });
};

const stopAllDiscoveries = async () => {
  await Zeroconf.stopAllDiscoveries();
};
```

### Listen for discovered services

Discovered services are delivered via events. A service is first reported as found without its hostname, port and IP addresses, and again as resolved once those are known. Both events carry the same `id`, so the resolved service replaces the found one. Only available on Android and iOS:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const addListeners = async () => {
  await Zeroconf.addListener('serviceFound', (event) => {
    console.log('Service found:', event.service.name);
  });
  await Zeroconf.addListener('serviceResolved', (event) => {
    console.log(
      'Service resolved:',
      event.service.ipv4Addresses,
      event.service.port,
    );
  });
  await Zeroconf.addListener('serviceUpdated', (event) => {
    console.log('Service updated:', event.service.name);
  });
  await Zeroconf.addListener('serviceLost', (event) => {
    console.log('Service lost:', event.service.name);
  });
  await Zeroconf.addListener('discoveryFailed', (event) => {
    console.error('Discovery failed:', event.message);
  });
};
```

### Resolve a service

By default, every found service is resolved automatically. Set `autoResolve` to `false` if your app only needs the names of the available services and resolve a service explicitly once the user selects it. Only available on Android and iOS:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const startDiscoveryWithoutAutoResolve = async () => {
  const { id } = await Zeroconf.startDiscovery({
    autoResolve: false,
    type: '_http._tcp',
  });
  return id;
};

const resolveService = async (id: string) => {
  const { service } = await Zeroconf.resolveServiceById({ id });
  return service;
};
```

### Let the user select a service

On Android 17 and newer, the operating system can display a service picker and deliver only the service that the user selected. No local network permission is required in this case. The option is ignored on iOS. Only available on Android:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const startDiscoveryWithPicker = async () => {
  const { id } = await Zeroconf.startDiscovery({
    androidUsePicker: true,
    type: '_http._tcp',
  });
  return id;
};
```

### Advertise a service

Advertise your own service so that other devices can find it. If the name is already taken on the network, the service is renamed automatically, so always use the returned name instead of the requested one. Only available on Android and iOS:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const startAdvertising = async () => {
  const { id, name } = await Zeroconf.startAdvertising({
    name: 'My Service',
    port: 8080,
    txtRecord: { path: '/api' },
    type: '_http._tcp',
  });
  return { id, name };
};

const stopAdvertising = async (id: string) => {
  await Zeroconf.stopAdvertisingById({ id });
};

const stopAllAdvertising = async () => {
  await Zeroconf.stopAllAdvertising();
};
```

If the service is renamed after it has been registered, for example because another device claimed the name in the meantime, the `advertisingNameChange` event is emitted:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const addListener = async () => {
  await Zeroconf.addListener('advertisingNameChange', (event) => {
    console.log(`Renamed from ${event.previousName} to ${event.name}.`);
  });
};
```

### Check and request permissions

Discovery and advertising require the local network permission. On Android below version 16, the permission does not exist and is always reported as `granted`. On iOS, the operating system provides no API to read the permission and it cannot be requested programmatically, so `requestPermissions()` only triggers the one-time system prompt and the status is never `granted` (see the [FAQ](#faq)). Only available on Android and iOS:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const checkPermissions = async () => {
  return Zeroconf.checkPermissions();
};

const requestPermissions = async () => {
  return Zeroconf.requestPermissions();
};
```

If the permission was denied, send the user to the native app settings:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

const openAppSettings = async () => {
  await Zeroconf.openAppSettings();
};
```

### Remove all listeners

Remove all listeners for this plugin when they are no longer needed:

```
import { Zeroconf } from '@capawesome-team/capacitor-zeroconf';

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

## API

- [`checkPermissions()`](#checkpermissions)
- [`openAppSettings()`](#openappsettings)
- [`requestPermissions()`](#requestpermissions)
- [`resolveServiceById(...)`](#resolveservicebyid)
- [`startAdvertising(...)`](#startadvertising)
- [`startDiscovery(...)`](#startdiscovery)
- [`stopAdvertisingById(...)`](#stopadvertisingbyid)
- [`stopAllAdvertising()`](#stopalladvertising)
- [`stopAllDiscoveries()`](#stopalldiscoveries)
- [`stopDiscoveryById(...)`](#stopdiscoverybyid)
- [`addListener('advertisingNameChange', ...)`](#addlisteneradvertisingnamechange-)
- [`addListener('discoveryFailed', ...)`](#addlistenerdiscoveryfailed-)
- [`addListener('serviceFound', ...)`](#addlistenerservicefound-)
- [`addListener('serviceLost', ...)`](#addlistenerservicelost-)
- [`addListener('serviceResolved', ...)`](#addlistenerserviceresolved-)
- [`addListener('serviceUpdated', ...)`](#addlistenerserviceupdated-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the status of the local network permission.

On **Android**, the local network permission only exists on Android 16+. On older versions, this method always returns `granted`.

On **iOS**, the system provides no API to read the local network permission. This method returns `prompt` until a denial has been observed during the current app launch, then `denied`. It never returns `granted`.

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### openAppSettings()

```
openAppSettings() => Promise<void>
```

Open the app settings so the user can grant or revoke the local network permission.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the local network permission.

On **Android**, the local network permission only exists on Android 16+. On older versions, this method always returns `granted`.

On **iOS**, the permission cannot be requested programmatically. This method triggers the one-time system prompt by briefly browsing for the first service type declared in `NSBonjourServices` and then returns the current status (`prompt` or `denied`, see `checkPermissions()`).

Only available on Android and iOS.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### resolveServiceById(...)

```
resolveServiceById(options: ResolveServiceByIdOptions) => Promise<ResolveServiceByIdResult>
```

Resolve a discovered service to get its hostname, port and IP addresses.

This is only needed when `autoResolve` was set to `false` or to refresh the data of an already resolved service. The first resolution of a service also emits the `serviceResolved` event; a refresh that changed the data of an already resolved service emits the `serviceUpdated` event.

Only available on Android and iOS.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `ResolveServiceByIdOptions` |

**Returns:** `Promise<ResolveServiceByIdResult>`

**Since:** 0.0.1

______________________________________________________________________

### startAdvertising(...)

```
startAdvertising(options: StartAdvertisingOptions) => Promise<StartAdvertisingResult>
```

Advertise a service on the local network.

If the service name is already taken, the service is automatically renamed (e.g. `My <a href="#service">Service` becomes `My <a href="#service">Service</a> (2)`). The returned name is the actually registered name. If the service is renamed later, the `advertisingNameChange` event is emitted.

Advertising is only active while the app is in the foreground.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `StartAdvertisingOptions` |

**Returns:** `Promise<StartAdvertisingResult>`

**Since:** 0.0.1

______________________________________________________________________

### startDiscovery(...)

```
startDiscovery(options: StartDiscoveryOptions) => Promise<StartDiscoveryResult>
```

Start discovering services of a given type on the local network.

Discovered services are delivered via the `serviceFound`, `serviceResolved`, `serviceUpdated` and `serviceLost` events.

Discovery is only active while the app is in the foreground. On **iOS**, the `serviceLost` event is emitted for all discovered services when the app enters the background and the discovery is automatically restarted when the app returns to the foreground.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `StartDiscoveryOptions` |

**Returns:** `Promise<StartDiscoveryResult>`

**Since:** 0.0.1

______________________________________________________________________

### stopAdvertisingById(...)

```
stopAdvertisingById(options: StopAdvertisingByIdOptions) => Promise<void>
```

Stop advertising a service.

Only available on Android and iOS.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `StopAdvertisingByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopAllAdvertising()

```
stopAllAdvertising() => Promise<void>
```

Stop advertising all services.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### stopAllDiscoveries()

```
stopAllDiscoveries() => Promise<void>
```

Stop all running discoveries.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### stopDiscoveryById(...)

```
stopDiscoveryById(options: StopDiscoveryByIdOptions) => Promise<void>
```

Stop a running discovery.

Only available on Android and iOS.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `StopDiscoveryByIdOptions` |

**Since:** 0.0.1

______________________________________________________________________

### addListener('advertisingNameChange', ...)

```
addListener(eventName: 'advertisingNameChange', listenerFunc: (event: AdvertisingNameChangeEvent) => void) => Promise<PluginListenerHandle>
```

Called when an advertised service was renamed by the network responder because of a name conflict.

Only available on Android and iOS.

| Param              | Type                                          |
| ------------------ | --------------------------------------------- |
| **`eventName`**    | `'advertisingNameChange'`                     |
| **`listenerFunc`** | `(event: AdvertisingNameChangeEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('discoveryFailed', ...)

```
addListener(eventName: 'discoveryFailed', listenerFunc: (event: DiscoveryFailedEvent) => void) => Promise<PluginListenerHandle>
```

Called when a running discovery fails. The discovery is stopped before this event is emitted.

Only available on Android and iOS.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'discoveryFailed'`                     |
| **`listenerFunc`** | `(event: DiscoveryFailedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('serviceFound', ...)

```
addListener(eventName: 'serviceFound', listenerFunc: (event: ServiceEvent) => void) => Promise<PluginListenerHandle>
```

Called when a service was found on the local network.

The service is not yet resolved at this point, so `hostname`, `port` and the IP addresses are not yet available.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'serviceFound'`                |
| **`listenerFunc`** | `(event: ServiceEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('serviceLost', ...)

```
addListener(eventName: 'serviceLost', listenerFunc: (event: ServiceEvent) => void) => Promise<PluginListenerHandle>
```

Called when a service disappeared from the local network.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'serviceLost'`                 |
| **`listenerFunc`** | `(event: ServiceEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('serviceResolved', ...)

```
addListener(eventName: 'serviceResolved', listenerFunc: (event: ServiceEvent) => void) => Promise<PluginListenerHandle>
```

Called when a service was resolved. The service now contains the hostname, port and IP addresses. It replaces the service delivered by the `serviceFound` event (same `id`).

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'serviceResolved'`             |
| **`listenerFunc`** | `(event: ServiceEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('serviceUpdated', ...)

```
addListener(eventName: 'serviceUpdated', listenerFunc: (event: ServiceEvent) => void) => Promise<PluginListenerHandle>
```

Called when the data of an already resolved service changed.

On **iOS**, this event is only emitted when the service is re-resolved via `resolveServiceById(...)`.

Only available on Android and iOS.

| Param              | Type                            |
| ------------------ | ------------------------------- |
| **`eventName`**    | `'serviceUpdated'`              |
| **`listenerFunc`** | `(event: ServiceEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop               | Type              | Description                                           | Since |
| ------------------ | ----------------- | ----------------------------------------------------- | ----- |
| **`localNetwork`** | `PermissionState` | The permission state for accessing the local network. | 0.0.1 |

#### ResolveServiceByIdResult

| Prop          | Type      | Description           | Since |
| ------------- | --------- | --------------------- | ----- |
| **`service`** | `Service` | The resolved service. | 0.0.1 |

#### Service

| Prop                | Type                     | Description                                                                                                                                                                                                                  | Since                                                                                            |
| ------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **`domain`**        | `string`                 | The domain of the service.                                                                                                                                                                                                   | 0.0.1                                                                                            |
| **`hostname`**      | \`string                 | null\`                                                                                                                                                                                                                       | The hostname of the device providing the service. Is `null` until the service has been resolved. |
| **`id`**            | `string`                 | The unique identifier of the service. The identifier is generated by the plugin and stays stable for the lifetime of the discovery, across the `serviceFound`, `serviceResolved`, `serviceUpdated` and `serviceLost` events. | 0.0.1                                                                                            |
| **`ipv4Addresses`** | `string[]`               | The IPv4 addresses of the device providing the service. Is empty until the service has been resolved.                                                                                                                        | 0.0.1                                                                                            |
| **`ipv6Addresses`** | `string[]`               | The IPv6 addresses of the device providing the service. Link-local addresses (`fe80::/10`) are filtered out. Is empty until the service has been resolved.                                                                   | 0.0.1                                                                                            |
| **`lastSeenAt`**    | `number`                 | The timestamp at which the service was last seen, in milliseconds since the Unix epoch.                                                                                                                                      | 0.0.1                                                                                            |
| **`name`**          | `string`                 | The name of the service.                                                                                                                                                                                                     | 0.0.1                                                                                            |
| **`port`**          | \`number                 | null\`                                                                                                                                                                                                                       | The port on which the service is available. Is `null` until the service has been resolved.       |
| **`txtRecord`**     | `Record<string, string>` | The TXT record of the service.                                                                                                                                                                                               | 0.0.1                                                                                            |
| **`type`**          | `string`                 | The type of the service.                                                                                                                                                                                                     | 0.0.1                                                                                            |

#### ResolveServiceByIdOptions

| Prop     | Type     | Description                               | Since |
| -------- | -------- | ----------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the service to resolve. | 0.0.1 |

#### StartAdvertisingResult

| Prop       | Type     | Description                                                                                                                                 | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`id`**   | `string` | The identifier of the advertised service.                                                                                                   | 0.0.1 |
| **`name`** | `string` | The actually registered name of the service. This may differ from the requested name if the service was renamed because of a name conflict. | 0.0.1 |

#### StartAdvertisingOptions

| Prop            | Type                     | Description                                                                                                                                                                 | Default    | Since |
| --------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| **`domain`**    | `string`                 | The domain in which to advertise the service.                                                                                                                               | `'local.'` | 0.0.1 |
| **`name`**      | `string`                 | The name of the service. If the name is already taken, the service is automatically renamed.                                                                                |            | 0.0.1 |
| **`port`**      | `number`                 | The port on which the service is available.                                                                                                                                 |            | 0.0.1 |
| **`txtRecord`** | `Record<string, string>` | The TXT record to advertise with the service. If not provided, a single default pair (`txtvers=1`) is advertised since some platforms cannot advertise an empty TXT record. |            | 0.0.1 |
| **`type`**      | `string`                 | The type of the service.                                                                                                                                                    |            | 0.0.1 |

#### StartDiscoveryResult

| Prop     | Type     | Description                      | Since |
| -------- | -------- | -------------------------------- | ----- |
| **`id`** | `string` | The identifier of the discovery. | 0.0.1 |

#### StartDiscoveryOptions

| Prop                   | Type      | Description                                                                                                                                                                                                              | Default    | Since |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----- |
| **`androidUsePicker`** | `boolean` | Whether or not to let the user select the service via a system dialog. In this case, no local network permission is required and only the selected service is delivered to the app. Only available on Android (SDK 37+). | `false`    | 0.0.1 |
| **`autoResolve`**      | `boolean` | Whether or not found services are automatically resolved. If set to `false`, services must be resolved manually using `resolveServiceById(...)`.                                                                         | `true`     | 0.0.1 |
| **`domain`**           | `string`  | The domain in which to discover services.                                                                                                                                                                                | `'local.'` | 0.0.1 |
| **`type`**             | `string`  | The type of the services to discover.                                                                                                                                                                                    |            | 0.0.1 |

#### StopAdvertisingByIdOptions

| Prop     | Type     | Description                                       | Since |
| -------- | -------- | ------------------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the advertised service to stop. | 0.0.1 |

#### StopDiscoveryByIdOptions

| Prop     | Type     | Description                              | Since |
| -------- | -------- | ---------------------------------------- | ----- |
| **`id`** | `string` | The identifier of the discovery to stop. | 0.0.1 |

#### PluginListenerHandle

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

#### AdvertisingNameChangeEvent

| Prop               | Type     | Description                                  | Since |
| ------------------ | -------- | -------------------------------------------- | ----- |
| **`id`**           | `string` | The identifier of the advertised service.    | 0.0.1 |
| **`name`**         | `string` | The new name of the advertised service.      | 0.0.1 |
| **`previousName`** | `string` | The previous name of the advertised service. | 0.0.1 |

#### DiscoveryFailedEvent

| Prop          | Type     | Description                                  | Since                          |
| ------------- | -------- | -------------------------------------------- | ------------------------------ |
| **`code`**    | \`string | null\`                                       | The error code of the failure. |
| **`id`**      | `string` | The identifier of the discovery that failed. | 0.0.1                          |
| **`message`** | `string` | The error message of the failure.            | 0.0.1                          |

#### ServiceEvent

| Prop              | Type      | Description                                               | Since |
| ----------------- | --------- | --------------------------------------------------------- | ----- |
| **`discoveryId`** | `string`  | The identifier of the discovery that delivered the event. | 0.0.1 |
| **`service`**     | `Service` | The service that the event refers to.                     | 0.0.1 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

## Service Types

A service type consists of a service name and a transport protocol, for example `_http._tcp` for a web server or `_ipp._tcp` for a network printer:

```
_<service>._tcp
_<service>._udp
```

The trailing dot is optional, so both `_http._tcp` and `_http._tcp.` are accepted. The plugin normalizes the type and always returns it **without** the trailing dot, so the `type` of a discovered service can be compared directly to the type you passed in. Domains are normalized the other way round and always carry the trailing dot, for example `local.`.

A malformed type is rejected immediately, instead of silently returning no results, with a message that shows the expected form:

```
type must be of the form _<service>._tcp or _<service>._udp (e.g. _http._tcp).
```

Registered service types are listed in the [IANA service name registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml). If you advertise your own protocol, pick a name that is not registered yet.

Two variants are deliberately not supported and are rejected with an explanatory message:

- **Service type enumeration** (`_services._dns-sd._udp`), because neither platform implements it reliably. Discover a concrete service type instead.
- **Subtypes** (for example `_printer._sub._http._tcp`), which are not supported yet.

## Foreground Only

Discovery and advertising are only active while the app is in the **foreground** on both platforms. This is a restriction of the operating systems and not of the plugin: Android only holds the multicast lock for an app that is currently in the foreground, and iOS closes the connection to the mDNS daemon as soon as the app is suspended, which happens within seconds after it is backgrounded. Neither platform offers a background mode for this.

The two platforms behave differently while the app is not in the foreground:

- On **iOS**, the plugin emits a `serviceLost` event for every currently known service when the app enters the background and tears down its native handles. When the app returns to the foreground, all running discoveries and all advertised services are restored automatically. If a service is registered under a different name afterwards, an `advertisingNameChange` event is emitted.
- On **Android**, the requests stay registered with the operating system, but no events are delivered while the app is in the background. Discovery continues on its own once the app returns to the foreground.

## FAQ

### How is this plugin different from other similar plugins?

It is built on the service discovery APIs that the operating systems maintain themselves: `NsdManager` on Android and the low-level DNS-SD C API on iOS. That matters right now, because both platforms are restricting local network access at the same time. Android 17 permission-gates the raw sockets that a bundled mDNS stack needs, and iOS deprecates the classic `NetService` API — this plugin is already on the other side of both changes, and it additionally supports the Android system picker, which returns the service the user selected without requiring any permission at all. On iOS, the `Info.plist` configuration is validated at runtime, so the single most common cause of "nothing is found" becomes an error message naming the exact entry to add, instead of an empty result and no error at all. Discovery and resolution are separate steps, so your app does not have to resolve every service it sees, and a resolved service carries its hostname, port, IPv4 and IPv6 addresses separately rather than one ambiguous address. On top of that, permissions are handled first class on both platforms, every runtime failure rejects with a documented error code, and the plugin comes with priority support from the Capawesome Team.

### Is service discovery available on the web?

No. All methods are only available on Android and iOS. On the web, they reject with an unimplemented error. Browsers deliberately do not expose mDNS to web content, and there is no active proposal that would change this.

### Which devices can I discover?

Every device that publishes a service via mDNS/DNS-SD, which includes implementations such as Apple Bonjour and Avahi as well as printers, media servers, network attached storage, and other apps using this plugin. Only the service type has to match.

### Why are no services found?

The most common causes, in this order: the app runs on the Android emulator, which cannot do multicast at all; the service type is not declared in `NSBonjourServices` on iOS, which fails silently on the operating system side; the devices are on different networks or on a network that isolates clients from each other; or the service type does not match exactly. See [Testing](#testing) for how to verify the network itself.

### Why are `hostname` and `port` `null`?

The service has been found but not resolved yet. Discovery reports the name, type and domain of a service first, and its hostname, port and IP addresses only after it has been resolved. Wait for the `serviceResolved` event or resolve the service explicitly with `resolveServiceById(...)`.

### Why does `checkPermissions()` never return `granted` on iOS?

iOS provides no API to read the state of the local network permission ([TN3179](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)). The plugin therefore reports `prompt` until a denial has actually been observed during the current app launch and `denied` afterwards, instead of pretending to know a state it cannot read.

### How many discoveries and advertisements can run at the same time?

On Android, the operating system limits the combined number of discoveries and advertisements per app to around ten. Once the limit is reached, `startDiscovery(...)` and `startAdvertising(...)` reject with the `MAX_REQUESTS_REACHED` error code. Stop the ones you no longer need instead of keeping them around.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity and read the network information of the device.
- [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Discover and communicate with nearby devices via Bluetooth.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zeroconf/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zeroconf/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zeroconf/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Apple Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `Bonjour` is a registered trademark of Apple Inc. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor Zip Plugin

Capacitor plugin to zip and unzip files and directories with support for encryption.

## Features

The Capacitor Zip plugin is one of the most complete file archiving solutions for Capacitor apps. Here are some of the key features:

- 🖥️ **Cross-platform**: Supports Android and iOS.
- 📁 **File Compression**: Zip and unzip single or multiple files.
- 🔑 **Encryption**: Encrypt and decrypt files.
- 🤝 **Compatibility**: Compatible with the [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugin.
- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
- ⭐️ **Support**: Priority support from the Capawesome Team.
- ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll add it for you!

## Use Cases

The Zip plugin is typically used whenever an app needs to work with zip archives, for example:

- **File uploads**: Bundle multiple files or an entire directory into a single zip archive before uploading it to a server.
- **Content downloads**: Unzip archives downloaded from a server, for example to make content available offline.
- **Data backups**: Compress app data into an archive that can be exported and restored later.
- **Sensitive data protection**: Encrypt archives with a password when zipping and decrypt them when unzipping.

## 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     |

## Demo

A working example can be found [here](https://github.com/robingenz/capacitor-plugin-demo).

## Installation

This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

**Attention**: Replace `<YOUR_LICENSE_KEY>` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/).

Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-zip` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capawesome-team/capacitor-zip
npx cap sync
```

### Android

#### Proguard

If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file:

```
-keep class io.capawesome.capacitorjs.plugins.** { *; }
```

#### 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:

- `$zip4jVersion` version of `net.lingala.zip4j:zip4j` (default: `2.11.5`)

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

### iOS

#### Minimum Deployment Target

If you are using **Swift Package Manager**, make sure that your iOS deployment target is set to at least `16.0` in your Xcode project settings (usually in `ios/App/App.xcodeproj`):

```
-IPHONEOS_DEPLOYMENT_TARGET = 15.0
+IPHONEOS_DEPLOYMENT_TARGET = 16.0
```

If you are using **CocoaPods**, make sure that your iOS deployment target is set to at least `16.0` in your `Podfile`:

```
platform :ios, '16.0'
```

## Configuration

No configuration required for this plugin.

## Usage

The following examples show how to create a zip archive and extract an existing one.

### Zip a file or directory

Create a zip archive from a source file or directory. You can optionally provide a `password` to encrypt the archive. Only available on Android and iOS:

```
import { Zip } from '@capawesome-team/capacitor-zip';

const zip = async () => {
  await Zip.zip({
    source: 'file:///data/user/0/dev.robingenz.capacitor.plugindemo/cache/1714900095398',
    destination: 'file:///data/user/0/dev.robingenz.capacitor.plugindemo/cache/1714900095398.zip',
    password: 'secret',
  });
};
```

### Unzip an archive

Extract a zip archive into a destination directory. If the archive is encrypted, provide the `password` to decrypt it. Only available on Android and iOS:

```
import { Zip } from '@capawesome-team/capacitor-zip';

const unzip = async () => {
  await Zip.unzip({
    source: 'file:///data/user/0/dev.robingenz.capacitor.plugindemo/cache/1714900095398.zip',
    destination: 'file:///data/user/0/dev.robingenz.capacitor.plugindemo/cache/1714900095398',
    password: 'secret',
  });
};
```

## API

- [`unzip(...)`](#unzip)
- [`zip(...)`](#zip)
- [Interfaces](#interfaces)

### unzip(...)

```
unzip(options: UnzipOptions) => Promise<void>
```

Unzip a file.

Only available on Android and iOS.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `UnzipOptions` |

**Since:** 6.0.0

______________________________________________________________________

### zip(...)

```
zip(options: ZipOptions) => Promise<void>
```

Zip a file or directory.

Only available on Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `ZipOptions` |

**Since:** 6.0.0

______________________________________________________________________

### Interfaces

#### UnzipOptions

| Prop              | Type     | Description                           | Since |
| ----------------- | -------- | ------------------------------------- | ----- |
| **`destination`** | `string` | The destination directory.            | 6.0.0 |
| **`password`**    | `string` | The password to decrypt the zip file. | 6.1.0 |
| **`source`**      | `string` | The source file to unzip.             | 6.0.0 |

#### ZipOptions

| Prop              | Type     | Description                           | Since |
| ----------------- | -------- | ------------------------------------- | ----- |
| **`destination`** | `string` | The destination file.                 | 6.0.0 |
| **`password`**    | `string` | The password to encrypt the zip file. | 6.1.0 |
| **`source`**      | `string` | The source file or directory to zip.  | 6.0.0 |

## FAQ

### Can I create password-protected zip archives?

Yes. Pass the `password` option to the `zip(...)` method to encrypt the archive and pass the same option to the `unzip(...)` method to decrypt it. See the [usage examples](#usage) above.

### Can I zip an entire directory?

Yes. The `source` option of the `zip(...)` method accepts either a single file or a directory. When unzipping, the archive is extracted into the directory specified by the `destination` option.

### Does this plugin work on the Web?

No, the `zip(...)` and `unzip(...)` methods are only available on Android and iOS, as documented in the [API](#api) section.

### How is this plugin different from the File Compressor plugin?

The [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugin reduces the file size of individual image files such as PNG, JPEG, and WebP. The Zip plugin, on the other hand, bundles one or more files or directories into a zip archive and extracts them again. Both plugins are compatible and can be used together, for example to compress images before zipping them.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress image files such as PNG, JPEG, and WebP.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a file with the default application.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file, directory, image, or video from the device.
- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive files shared from other apps.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zip/CHANGELOG.md).

## Breaking Changes

See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zip/BREAKING.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/zip/LICENSE).

# Firebase Plugins

Our Capacitor Firebase plugins wrap the native Firebase SDKs behind a single JavaScript API, so you can use Firebase services in your Capacitor app across Android, iOS, and the Web.

These are unofficial, open-source plugins maintained by Capawesome. Open a plugin's page for installation steps, supported platforms, and the full API reference.

## Plugins

- [Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/index.md) — Track user interactions and events in your app.
- [App](https://capawesome.io/docs/sdks/capacitor/firebase/app/index.md) — Initialize Firebase in your app.
- [App Check](https://capawesome.io/docs/sdks/capacitor/firebase/app-check/index.md) — Protect your backend resources from abuse.
- [Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/index.md) — Authenticate users with email, phone, and social providers.
- [Crashlytics](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/index.md) — Report crashes and non-fatal errors.
- [Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) — Store and sync data in real time.
- [Cloud Functions](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/index.md) — Call backend Cloud Functions from your app.
- [Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/index.md) — Receive push notifications via FCM.
- [Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/index.md) — Upload and download files.
- [Performance Monitoring](https://capawesome.io/docs/sdks/capacitor/firebase/performance-monitoring/index.md) — Measure app performance and find bottlenecks.
- [Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/index.md) — Manage configurations and feature flags remotely.

## FAQ

### What are the Capacitor Firebase plugins?

They are packages that expose the native Firebase SDKs through a unified JavaScript API, letting you use Firebase in a Capacitor app without writing native code yourself. To learn more about the underlying services, see the [official Firebase documentation](https://firebase.google.com/docs).

### Are these Firebase plugins free?

Yes. All Firebase plugins listed here are open source and free to use.

### Which platforms do the plugins support?

Most plugins support Android, iOS, and Web. The supported platforms are listed at the top of each plugin's documentation page.

### How do I get support?

For bugs and feature requests, open an issue on the plugin's GitHub repository. For dedicated help, see our [support options](/docs/support/).

## Guides

Here are some guides to help you get started with Firebase in your Capacitor app:

- [Firebase Authentication in Capacitor: Setup & Best Practices](https://capawesome.io/blog/capacitor-firebase-authentication-guide/index.md)
- [Capacitor Firestore: Real-Time Data & Offline Sync](https://capawesome.io/blog/capacitor-firebase-cloud-firestore-guide/index.md)
- [Upload & Manage Files with Firebase Storage in Capacitor](https://capawesome.io/blog/capacitor-firebase-cloud-storage-guide/index.md)
- [Track App Events with Firebase Analytics in Capacitor](https://capawesome.io/blog/capacitor-firebase-analytics-guide/index.md)
- [Crash Reporting in a Capacitor App with Crashlytics](https://capawesome.io/blog/capacitor-firebase-crashlytics-guide/index.md)
- [Firebase App Check in a Capacitor App](https://capawesome.io/blog/capacitor-firebase-app-check-guide/index.md)
- [Capacitor Push Notifications: The Complete Guide](https://capawesome.io/blog/capacitor-push-notifications-guide/index.md)
- [How to Wrap an Angular App with Capacitor and Firebase](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/index.md)

## Next steps

- Browse all our [Capacitor plugins](https://capawesome.io/docs/sdks/capacitor/index.md).
- Add push notifications with the [Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/index.md) plugin.
- Explore [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) for Live Updates, Native Builds, and App Store Publishing.
- View the source on [GitHub](https://github.com/capawesome-team).

# Capacitor Firebase Analytics Plugin

Unofficial Capacitor plugin for [Firebase Analytics](https://firebase.google.com/docs/analytics).[1](#fn:1)

## Use Cases

The Firebase Analytics plugin is typically used to understand how users interact with your app, for example:

- **Event tracking**: Log app events such as sign-ups with custom parameters using `logEvent(...)`.
- **Screen tracking**: Record which screens users visit using `setCurrentScreen(...)`.
- **Audience segmentation**: Assign user IDs and custom user properties to segment your users.
- **Consent management**: Set the user's consent mode and enable or disable data collection to comply with privacy requirements.
- **Conversion measurement**: Initiate on-device conversion measurement with an email address or phone number on iOS.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [Track App Events with Firebase Analytics in Capacitor](https://capawesome.io/blog/capacitor-firebase-analytics-guide/): Log events, track screens, and set up audience segmentation with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): Where Analytics sits among the other Firebase plugins, and what teams usually add alongside it.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/analytics` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/analytics firebase
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

#### Disable Analytics data collection

See [Disable Analytics data collection](https://firebase.google.com/docs/analytics/configure-data-collection?platform=android#disable_data_collection) if you want to disable Analytics data collection.

#### Disable Advertising ID collection

See [Disable Advertising ID collection](https://firebase.google.com/docs/analytics/configure-data-collection?platform=android#disable_advertising_id_collection) if you want to disable Advertising ID collection.

#### 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:

- `$firebaseAnalyticsVersion` version of `com.google.firebase:firebase-analytics` (default: `23.0.0`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/analytics": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

If you are using **CocoaPods** for your iOS project, you need to add the `CapacitorFirebaseAnalytics/Analytics` pod to your `Podfile` (usually `ios/App/Podfile`):

```
target 'App' do
capacitor_pods
# Add your Pods here
+  pod 'CapacitorFirebaseAnalytics/Analytics', :path => '../../node_modules/@capacitor-firebase/analytics'
end
```

**Attention**: Do not add the pod in the section `def capacitor_pods`, but under the comment `# Add your Pods here` ([example](https://github.com/robingenz/capacitor-firebase-plugin-demo/blob/e1684a0af6871442ed0a87dceeeba6fd9ce0185d/ios/App/Podfile#L30)).

#### Disable Analytics data collection

See [Disable Analytics data collection](https://firebase.google.com/docs/analytics/configure-data-collection?platform=ios#disable_data_collection) if you want to disable Analytics data collection.

#### Disable IDFA collection

If you are using **CocoaPods** for your iOS project and you want to disable IDFA collection, you can use the `CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport` pod instead of the `CapacitorFirebaseAnalytics/Analytics` pod:

```
target 'App' do
capacitor_pods
# Add your Pods here
-  pod 'CapacitorFirebaseAnalytics/Analytics', :path => '../../node_modules/@capacitor-firebase/analytics'
+  pod 'CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport', :path => '../../node_modules/@capacitor-firebase/analytics'
end
```

If you are using **Swift Package Manager** for your iOS project and you want to disable IDFA collection, you can enable the `AnalyticsWithoutAdIdSupport` trait in your `capacitor.config.json` (or `capacitor.config.ts`):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capacitor-firebase/analytics": ["AnalyticsWithoutAdIdSupport"]
        }
      }
    }
  }
}
```

**Note**: SPM trait support requires Capacitor CLI **8.3.0+** and Xcode **16.3+** (Swift 6.1+).

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Usage

The following examples show how to log events, track screens, identify users, manage data collection, configure the session timeout, and initiate on-device conversion measurement.

### Log events

Log an app event with a name and optional parameters:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const logEvent = async () => {
  await FirebaseAnalytics.logEvent({
    name: 'sign_up',
    params: { method: 'password' },
  });
};
```

### Track screens

Set the current screen name to record which screens users visit. The `screenClassOverride` option is only available on Android and iOS:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setCurrentScreen = async () => {
  await FirebaseAnalytics.setCurrentScreen({
    screenName: 'Login',
    screenClassOverride: 'LoginPage',
  });
};
```

### Identify users

Set the user ID property and custom user properties to segment your users:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setUserId = async () => {
  await FirebaseAnalytics.setUserId({
    userId: '123',
  });
};

const setUserProperty = async () => {
  await FirebaseAnalytics.setUserProperty({
    key: 'language',
    value: 'en',
  });
};
```

### Manage data collection

Enable or disable automatic data collection (the value does not apply until the next run of the app), check whether it is enabled (only available on Web), or clear all analytics data from the device (only available on Android and iOS):

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setEnabled = async () => {
  await FirebaseAnalytics.setEnabled({
    enabled: true,
  });
};

const isEnabled = async () => {
  const { enabled } = await FirebaseAnalytics.isEnabled();
  return enabled;
};

const resetAnalyticsData = async () => {
  await FirebaseAnalytics.resetAnalyticsData();
};
```

### Configure the session timeout

Set the duration of inactivity that terminates the current session. Only available on Android and iOS:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const setSessionTimeoutDuration = async () => {
  await FirebaseAnalytics.setSessionTimeoutDuration({
    duration: '120',
  });
};
```

### Initiate on-device conversion measurement

Initiate on-device conversion measurement with a plain or hashed email address or phone number. Only available on iOS:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const initiateOnDeviceConversionMeasurementWithEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithEmailAddress({
    emailAddress: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithPhoneNumber({
    phoneNumber: '+49123456789',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedEmailAddress({
    emailAddressToHash: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedPhoneNumber({
    phoneNumberToHash: '+49123456789',
  });
};
```

## API

- [`getAppInstanceId()`](#getappinstanceid)
- [`setConsent(...)`](#setconsent)
- [`setUserId(...)`](#setuserid)
- [`setUserProperty(...)`](#setuserproperty)
- [`setCurrentScreen(...)`](#setcurrentscreen)
- [`logEvent(...)`](#logevent)
- [`setSessionTimeoutDuration(...)`](#setsessiontimeoutduration)
- [`setEnabled(...)`](#setenabled)
- [`isEnabled()`](#isenabled)
- [`resetAnalyticsData()`](#resetanalyticsdata)
- [`logTransaction(...)`](#logtransaction)
- [`initiateOnDeviceConversionMeasurementWithEmailAddress(...)`](#initiateondeviceconversionmeasurementwithemailaddress)
- [`initiateOnDeviceConversionMeasurementWithPhoneNumber(...)`](#initiateondeviceconversionmeasurementwithphonenumber)
- [`initiateOnDeviceConversionMeasurementWithHashedEmailAddress(...)`](#initiateondeviceconversionmeasurementwithhashedemailaddress)
- [`initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(...)`](#initiateondeviceconversionmeasurementwithhashedphonenumber)
- [Interfaces](#interfaces)
- [Enums](#enums)

### getAppInstanceId()

```
getAppInstanceId() => Promise<GetAppInstanceIdResult>
```

Retrieves the app instance id.

Only available for Android and iOS.

**Returns:** `Promise<GetAppInstanceIdResult>`

**Since:** 1.4.0

______________________________________________________________________

### setConsent(...)

```
setConsent(options: SetConsentOptions) => Promise<void>
```

Sets the user's consent mode.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetConsentOptions` |

**Since:** 6.0.0

______________________________________________________________________

### setUserId(...)

```
setUserId(options: SetUserIdOptions) => Promise<void>
```

Sets the user ID property.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetUserIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setUserProperty(...)

```
setUserProperty(options: SetUserPropertyOptions) => Promise<void>
```

Sets a custom user property to a given value.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetUserPropertyOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setCurrentScreen(...)

```
setCurrentScreen(options: SetCurrentScreenOptions) => Promise<void>
```

Sets the current screen name.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetCurrentScreenOptions` |

**Since:** 0.1.0

______________________________________________________________________

### logEvent(...)

```
logEvent(options: LogEventOptions) => Promise<void>
```

Logs an app event.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `LogEventOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setSessionTimeoutDuration(...)

```
setSessionTimeoutDuration(options: SetSessionTimeoutDurationOptions) => Promise<void>
```

Sets the duration of inactivity that terminates the current session.

Only available for Android and iOS.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `SetSessionTimeoutDurationOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setEnabled(...)

```
setEnabled(options: SetEnabledOptions) => Promise<void>
```

Enables/disables automatic data collection. The value does not apply until the next run of the app.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetEnabledOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Returns whether or not automatic data collection is enabled.

Only available for Web.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### resetAnalyticsData()

```
resetAnalyticsData() => Promise<void>
```

Clears all analytics data for this app from the device. Resets the app instance id.

Only available for Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### logTransaction(...)

```
logTransaction(options: LogTransactionOptions) => Promise<void>
```

Logs a StoreKit 2 transaction.

Only available for iOS (15.0+).

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `LogTransactionOptions` |

**Since:** 8.2.0

______________________________________________________________________

### initiateOnDeviceConversionMeasurementWithEmailAddress(...)

```
initiateOnDeviceConversionMeasurementWithEmailAddress(options: InitiateOnDeviceConversionMeasurementWithEmailAddressOptions) => Promise<void>
```

Initiates on-device conversion measurement with an email address.

Only available for iOS.

| Param         | Type                                                           |
| ------------- | -------------------------------------------------------------- |
| **`options`** | `InitiateOnDeviceConversionMeasurementWithEmailAddressOptions` |

**Since:** 7.2.0

______________________________________________________________________

### initiateOnDeviceConversionMeasurementWithPhoneNumber(...)

```
initiateOnDeviceConversionMeasurementWithPhoneNumber(options: InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions) => Promise<void>
```

Initiates on-device conversion measurement with a phone number.

Only available for iOS.

| Param         | Type                                                          |
| ------------- | ------------------------------------------------------------- |
| **`options`** | `InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions` |

**Since:** 7.2.0

______________________________________________________________________

### initiateOnDeviceConversionMeasurementWithHashedEmailAddress(...)

```
initiateOnDeviceConversionMeasurementWithHashedEmailAddress(options: InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions) => Promise<void>
```

Initiates on-device conversion measurement with a hashed email address.

Only available for iOS.

| Param         | Type                                                                 |
| ------------- | -------------------------------------------------------------------- |
| **`options`** | `InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions` |

**Since:** 7.2.0

______________________________________________________________________

### initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(...)

```
initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(options: InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions) => Promise<void>
```

Initiates on-device conversion measurement with a hashed phone number.

Only available for iOS.

| Param         | Type                                                                |
| ------------- | ------------------------------------------------------------------- |
| **`options`** | `InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions` |

**Since:** 7.2.0

______________________________________________________________________

### Interfaces

#### GetAppInstanceIdResult

| Prop                | Type     | Description                                                                                                                                                                                             | Since |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`appInstanceId`** | `string` | The app instance id. Not defined if `FirebaseAnalytics.<a href="#consenttype">ConsentType</a>.ANALYTICS_STORAGE` has been set to `FirebaseAnalytics.<a href="#consentstatus">ConsentStatus</a>.DENIED`. | 1.4.0 |

#### SetConsentOptions

| Prop         | Type            | Description         | Since |
| ------------ | --------------- | ------------------- | ----- |
| **`type`**   | `ConsentType`   | The consent type.   | 6.0.0 |
| **`status`** | `ConsentStatus` | The consent status. | 6.0.0 |

#### SetUserIdOptions

| Prop         | Type     | Since  |
| ------------ | -------- | ------ |
| **`userId`** | \`string | null\` |

#### SetUserPropertyOptions

| Prop        | Type     | Since  |
| ----------- | -------- | ------ |
| **`key`**   | `string` | 0.1.0  |
| **`value`** | \`string | null\` |

#### SetCurrentScreenOptions

| Prop                      | Type     | Description | Default                             | Since  |
| ------------------------- | -------- | ----------- | ----------------------------------- | ------ |
| **`screenName`**          | \`string | null\`      |                                     |        |
| **`screenClassOverride`** | \`string | null\`      | Only available for Android and iOS. | `null` |

#### LogEventOptions

| Prop         | Type                      | Description                | Since |
| ------------ | ------------------------- | -------------------------- | ----- |
| **`name`**   | `string`                  | The event name.            | 0.1.0 |
| **`params`** | `{ [key: string]: any; }` | The optional event params. | 0.1.0 |

#### SetSessionTimeoutDurationOptions

| Prop           | Type     | Description          | Default | Since |
| -------------- | -------- | -------------------- | ------- | ----- |
| **`duration`** | `number` | Duration in seconds. | `1800`  | 0.1.0 |

#### SetEnabledOptions

| Prop          | Type      | Since |
| ------------- | --------- | ----- |
| **`enabled`** | `boolean` | 0.1.0 |

#### IsEnabledResult

| Prop          | Type      | Since |
| ------------- | --------- | ----- |
| **`enabled`** | `boolean` | 0.1.0 |

#### LogTransactionOptions

| Prop                | Type     | Description                                                | Since |
| ------------------- | -------- | ---------------------------------------------------------- | ----- |
| **`transactionId`** | `string` | The StoreKit 2 `Transaction.id` value as a numeric string. | 8.2.0 |

#### InitiateOnDeviceConversionMeasurementWithEmailAddressOptions

| Prop               | Type     | Description                                                          | Since |
| ------------------ | -------- | -------------------------------------------------------------------- | ----- |
| **`emailAddress`** | `string` | The email address to initiate on-device conversion measurement with. | 7.2.0 |

#### InitiateOnDeviceConversionMeasurementWithPhoneNumberOptions

| Prop              | Type     | Description                                                         | Since |
| ----------------- | -------- | ------------------------------------------------------------------- | ----- |
| **`phoneNumber`** | `string` | The phone number to initiate on-device conversion measurement with. | 7.2.0 |

#### InitiateOnDeviceConversionMeasurementWithHashedEmailAddressOptions

| Prop                     | Type     | Description                                                          | Since |
| ------------------------ | -------- | -------------------------------------------------------------------- | ----- |
| **`emailAddressToHash`** | `string` | The email address to initiate on-device conversion measurement with. | 7.2.0 |

#### InitiateOnDeviceConversionMeasurementWithHashedPhoneNumberOptions

| Prop                    | Type     | Description                                                         | Since |
| ----------------------- | -------- | ------------------------------------------------------------------- | ----- |
| **`phoneNumberToHash`** | `string` | The phone number to initiate on-device conversion measurement with. | 7.2.0 |

### Enums

#### ConsentType

| Members                      | Value                       | Since |
| ---------------------------- | --------------------------- | ----- |
| **`AdPersonalization`**      | `'AD_PERSONALIZATION'`      | 6.0.0 |
| **`AdStorage`**              | `'AD_STORAGE'`              | 6.0.0 |
| **`AdUserData`**             | `'AD_USER_DATA'`            | 6.0.0 |
| **`AnalyticsStorage`**       | `'ANALYTICS_STORAGE'`       | 6.0.0 |
| **`FunctionalityStorage`**   | `'FUNCTIONALITY_STORAGE'`   | 6.0.0 |
| **`PersonalizationStorage`** | `'PERSONALIZATION_STORAGE'` | 6.0.0 |

#### ConsentStatus

| Members       | Value       | Since |
| ------------- | ----------- | ----- |
| **`Granted`** | `'GRANTED'` | 6.0.0 |
| **`Denied`**  | `'DENIED'`  | 6.0.0 |

## Test your implementation

[Here](https://firebase.google.com/docs/analytics/debugview) you can find more information on how to test the Firebase Analytics implementation using the **DebugView**.

## FAQ

### How can I verify that my events are being logged?

Use the **DebugView** in the Firebase console to inspect events as they are logged by your app. See the [DebugView documentation](https://firebase.google.com/docs/analytics/debugview) for more information on how to test your Firebase Analytics implementation.

### How can I disable analytics data collection?

You can enable or disable automatic data collection at runtime using the `setEnabled(...)` method; note that the value does not apply until the next run of the app. To disable data collection by default, follow the platform-specific instructions linked in the [Installation](#installation) section for Android and iOS.

### How do I set the user's consent mode?

Call the `setConsent(...)` method with a consent type (for example analytics storage or ad storage) and a consent status (granted or denied). This allows you to manage what data is collected based on the user's consent.

### Why is the app instance ID not defined?

The `appInstanceId` returned by `getAppInstanceId()` is not defined if the analytics storage consent type has been set to denied via `setConsent(...)`. Also note that `getAppInstanceId()` is only available on Android and iOS.

### How do I disable Advertising ID or IDFA collection?

On Android, follow the [Disable Advertising ID collection](https://firebase.google.com/docs/analytics/configure-data-collection?platform=android#disable_advertising_id_collection) guide. On iOS, use the `CapacitorFirebaseAnalytics/AnalyticsWithoutAdIdSupport` pod instead of the `CapacitorFirebaseAnalytics/Analytics` pod if you are using CocoaPods, or enable the `AnalyticsWithoutAdIdSupport` package trait if you are using Swift Package Manager. See the [Installation](#installation) section for details.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase App](https://capawesome.io/docs/sdks/capacitor/firebase/app/): Access the core Firebase app configuration.
- [Firebase Crashlytics](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/): Track and report app crashes with Firebase Crashlytics.
- [Firebase Performance Monitoring](https://capawesome.io/docs/sdks/capacitor/firebase/performance-monitoring/): Measure the performance of your app with Firebase Performance Monitoring.
- [Firebase Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/): Change the behavior and appearance of your app without publishing an app update.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/analytics/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/analytics/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase App Check Plugin

Unofficial Capacitor plugin for [Firebase App Check](https://firebase.google.com/docs/app-check).[1](#fn:1)

## Use Cases

The Firebase App Check plugin is typically used to verify that requests to your backend originate from your authentic app, for example:

- **Protecting Firebase resources**: Ensure that only your genuine app can access services like Cloud Firestore or Cloud Functions by attesting requests with Play Integrity, App Attest, or reCAPTCHA v3.
- **Securing custom backends**: Retrieve an App Check token with `getToken(...)` and send it along with requests to your own backend for server-side verification.
- **Automatic token refresh**: Keep App Check tokens up to date with `setTokenAutoRefreshEnabled(...)` and react to changes via the `tokenChanged` listener.
- **Local development**: Use the debug provider to test your app on unverified devices such as emulators.

## 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     |

## Guides

- [Firebase App Check in a Capacitor App](https://capawesome.io/blog/capacitor-firebase-app-check-guide/): Set up the Play Integrity, App Attest, and reCAPTCHA providers and verify tokens server-side with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): A tour of the Firebase services App Check ends up protecting once enforcement is on.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/app-check` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

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

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

See [Set up your Firebase project](https://firebase.google.com/docs/app-check/android/play-integrity-provider#project-setup) 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.

### iOS

On **iOS 14 and later**, see [Set up your Firebase project](https://firebase.google.com/docs/app-check/ios/app-attest-provider#project-setup) and follow the instructions to set up your app correctly.

On **iOS 13**, see [Set up your Firebase project](https://firebase.google.com/docs/app-check/ios/devicecheck-provider#project-setup) 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.

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/app-check": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

### Web

See [Set up your Firebase project](https://firebase.google.com/docs/app-check/web/recaptcha-provider#project-setup) and follow the instructions to set up your app correctly.

## Configuration

No configuration required for this plugin.

## Firebase JavaScript SDK

[Here](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/docs/firebase-js-sdk.md) 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](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Usage

The following examples show how to initialize App Check, get the current token, enable automatic token refresh, and listen for token changes.

### Initialize App Check

Activate App Check for your app. This can be called only once per app. On the Web, pass a provider such as `ReCaptchaV3Provider`; on Android and iOS, the native attestation providers are used:

```
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,
  });
};
```

### Get the current App Check token

Retrieve the current App Check token, for example to send it to your own backend. Set `forceRefresh` to `true` if you always want to fetch a fresh token instead of a cached one:

```
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

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

### Enable automatic token refresh

Set whether the App Check token should be refreshed automatically as needed:

```
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

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

### Listen for token changes

Get notified whenever the App Check token changes:

```
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

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

### Remove all listeners

Remove all listeners for this plugin. Only available on Web:

```
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

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

## API

- [`getToken(...)`](#gettoken)
- [`initialize(...)`](#initialize)
- [`setTokenAutoRefreshEnabled(...)`](#settokenautorefreshenabled)
- [`addListener('tokenChanged', ...)`](#addlistenertokenchanged-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### getToken(...)

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

Get the current App Check token.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `GetTokenOptions` |

**Returns:** `Promise<GetTokenResult>`

**Since:** 1.3.0

______________________________________________________________________

### initialize(...)

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

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

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `InitializeOptions` |

**Since:** 1.3.0

______________________________________________________________________

### setTokenAutoRefreshEnabled(...)

```
setTokenAutoRefreshEnabled(options: SetTokenAutoRefreshEnabledOptions) => Promise<void>
```

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

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `SetTokenAutoRefreshEnabledOptions` |

**Since:** 1.3.0

______________________________________________________________________

### addListener('tokenChanged', ...)

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

Called when the App Check token changed.

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

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 1.3.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available for Web.

**Since:** 1.3.0

______________________________________________________________________

### Interfaces

#### 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` |
| **`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 |

### Type Aliases

#### TokenChangedListener

Callback to receive the token change event.

`(event: TokenChangedEvent): void`

## Testing

### Android

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](https://console.firebase.google.com/u/0/project/_/appcheck/apps) in the Firebase Console and select Manage debug tokens from the overflow menu of your app. Then, register the debug secret from the output.

## FAQ

### Which attestation providers does this plugin use?

On Android, the plugin uses the [Play Integrity](https://firebase.google.com/docs/app-check/android/play-integrity-provider#project-setup) provider. On iOS, it uses [App Attest](https://firebase.google.com/docs/app-check/ios/app-attest-provider#project-setup) on iOS 14 and later and [DeviceCheck](https://firebase.google.com/docs/app-check/ios/devicecheck-provider#project-setup) on iOS 13. On the Web, it uses [reCAPTCHA v3](https://firebase.google.com/docs/app-check/web/recaptcha-provider#project-setup) by default, but you can also pass a `ReCaptchaEnterpriseProvider` or `CustomProvider` instance via the `provider` option.

### How can I test App Check on emulators and other unverified devices?

Use the debug provider by setting the `debugToken` option of the `initialize(...)` method. On Android, you can grab the temporary debug secret from the device logs and register it in the Firebase Console (see [Testing](#testing)). Never use the debug provider in production builds of your app and never share your debug builds with untrusted parties, as it allows access to your Firebase resources from unverified devices.

### How do I protect my own backend with App Check?

Call the `getToken(...)` method to retrieve the current App Check token in JWT format and send it along with requests to your backend, where you can verify it server-side. Use the `tokenChanged` listener to get notified whenever the token changes.

### Why is my App Check token not refreshed automatically?

Automatic token refresh is disabled by default. You can enable it with the `isTokenAutoRefreshEnabled` option of the `initialize(...)` method or at any time with the `setTokenAutoRefreshEnabled(...)` method.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Unofficial Capacitor plugin for Firebase Authentication.
- [Firebase Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/): Unofficial Capacitor plugin for Firebase Cloud Firestore.
- [Firebase Cloud Functions](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/): Unofficial Capacitor plugin for Firebase Cloud Functions.
- [Firebase Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/): Unofficial Capacitor plugin for Firebase Cloud Storage.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase App Plugin

Unofficial Capacitor plugin for [Firebase App](https://firebase.google.com/docs).[1](#fn:1)

## Use Cases

The Firebase App plugin is typically used to access the core Firebase configuration of your app, for example:

- **Configuration checks**: Read the Firebase configuration options such as the API key, application ID, and project ID at runtime to verify that the app is connected to the correct Firebase project.
- **Multi-environment apps**: Distinguish between staging and production builds by inspecting the Google Cloud project ID.
- **Debug screens**: Display Firebase project details such as the storage bucket or database URL in an internal debug view.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): The starting point for the whole plugin family and the setup every Firebase plugin shares.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/app` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

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

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

#### 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:

- `$firebaseCommonVersion` version of `com.google.firebase:firebase-common` (default: `22.0.1`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/app": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Usage

The following examples show how to get the Firebase app name and its configuration options.

### Get the app name

Retrieve the unique name of the Firebase app:

```
import { FirebaseApp } from '@capacitor-firebase/app';

const getName = async () => {
  const result = await FirebaseApp.getName();
};
```

### Get the Firebase configuration options

Retrieve the configuration options of the Firebase app, such as the API key, application ID, and project ID:

```
import { FirebaseApp } from '@capacitor-firebase/app';

const getOptions = async () => {
  const result = await FirebaseApp.getOptions();
};
```

## API

- [`getName()`](#getname)
- [`getOptions()`](#getoptions)
- [Interfaces](#interfaces)

### getName()

```
getName() => Promise<GetNameResult>
```

Get the name for this app.

**Returns:** `Promise<GetNameResult>`

**Since:** 0.1.0

______________________________________________________________________

### getOptions()

```
getOptions() => Promise<GetOptionsResult>
```

Get the configuration options for this app.

**Returns:** `Promise<GetOptionsResult>`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### GetNameResult

| Prop       | Type     | Description                  | Since |
| ---------- | -------- | ---------------------------- | ----- |
| **`name`** | `string` | The unique name of this app. | 0.1.0 |

#### GetOptionsResult

| Prop                | Type     | Description                                                    | Since |
| ------------------- | -------- | -------------------------------------------------------------- | ----- |
| **`apiKey`**        | `string` | API key used for authenticating requests from your app.        | 0.1.0 |
| **`applicationId`** | `string` | Google App ID used to uniquely identify an instance of an app. | 0.1.0 |
| **`databaseUrl`**   | `string` | The database root URL.                                         | 0.1.0 |
| **`gcmSenderId`**   | `string` | The Project Number.                                            | 0.1.0 |
| **`projectId`**     | `string` | The Google Cloud project ID.                                   | 0.1.0 |
| **`storageBucket`** | `string` | The Google Cloud Storage bucket name.                          | 0.1.0 |

## FAQ

### Which platforms does this plugin support?

The plugin supports Android, iOS, and Web. Both `getName()` and `getOptions()` are available on all three platforms.

### Do I need to configure anything before using this plugin?

No plugin-specific configuration is required. However, you must add Firebase to your project first. The [Installation](#installation) section links to the Firebase setup instructions for Android, iOS, and Web.

### What information does `getOptions` return?

The `getOptions()` method returns the configuration options of the Firebase app: the API key used for authenticating requests, the Google App ID, the database root URL, the project number, the Google Cloud project ID, and the Google Cloud Storage bucket name.

### How do I fix the SwiftPM package identity collision on iOS?

If you are using Swift Package Manager, add the `symlink` package option for `@capacitor-firebase/app` to your Capacitor configuration as described in the [Installation](#installation) section. Note that SPM `packageOptions` support requires Capacitor CLI 8.4.0 or later.

### Is this an official Firebase plugin?

No, this is an unofficial Capacitor plugin for the Firebase App SDK. The project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and track user interactions with Firebase Analytics.
- [Firebase Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Authenticate users with Firebase Authentication.
- [Firebase Crashlytics](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/): Track and report app crashes with Firebase Crashlytics.
- [Firebase Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/): Receive push notifications with Firebase Cloud Messaging.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Authentication Plugin

Unofficial Capacitor plugin for [Firebase Authentication](https://firebase.google.com/docs/auth).[1](#fn:1)

## Use Cases

The Firebase Authentication plugin is typically used to handle the entire sign-in flow of an app, for example:

- **Social logins**: Sign in users natively with Apple, Google, Facebook, Microsoft, GitHub, Twitter, Yahoo, Play Games, or Game Center.
- **Email-based authentication**: Register and sign in users with email and password, or send them a passwordless sign-in link.
- **Phone number sign-in**: Verify users with an SMS code sent to their phone number.
- **Guest access**: Let users try your app with anonymous sign-in and link a permanent account later.
- **Custom backends**: Sign in with custom tokens or OpenID Connect and retrieve ID tokens to authenticate requests to your own backend.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [Firebase Authentication in Capacitor: Setup & Best Practices](https://capawesome.io/blog/capacitor-firebase-authentication-guide/): Setup and best practices for sign-in flows with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): Why sign-in is usually the first Firebase piece to wire up, and what builds on the user ID it produces.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/authentication` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/authentication firebase
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

On **iOS**, verify that this function is included in your app's `AppDelegate.swift`:

```
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}
```

**Attention**: If you use this plugin on **iOS** in combination with `@capacitor-firebase/messaging`, then add the following to your app's `AppDelegate.swift`:

```
+ import FirebaseAuth

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    if Auth.auth().canHandle(url) {
+      return true
+    }
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}
```

The further installation steps depend on the selected authentication method:

- [Apple Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-apple.md)
- [Facebook Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-facebook.md)
- [Game Center Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-game-center.md)
- [GitHub Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-github.md)
- [Google Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-google.md)
- [Microsoft Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-microsoft.md)
- [OpenID Connect Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-oidc.md)
- [Play Games Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-play-games.md)
- [Twitter Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-twitter.md)
- [Yahoo Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-yahoo.md)
- [Anonymous Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-anonymous.md)
- [Email Link Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-email-link.md)
- [Phone Number Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-phone.md)
- [Custom Token Sign-In](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/setup-custom-token.md)

**Attention**: Please note that this plugin uses third-party SDKs to offer native sign-in. These SDKs can initialize on their own and collect various data. For more information, see [Third-Party SDKs](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/third-party-sdks.md).

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/authentication": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

##### Package traits

The GoogleSignIn and Facebook SDKs are optional and are included by default via the `Google` and `Facebook` package traits. If you do not use these providers, disable the corresponding trait so that the SDK is not linked into your app:

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capacitor-firebase/authentication": ["Google"]
        }
      }
    }
  }
}
```

Listing traits explicitly replaces the defaults, so only the traits you list are enabled. The example above keeps GoogleSignIn and excludes the Facebook SDK. Use the `Lite` trait to exclude both:

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capacitor-firebase/authentication": ["Lite"]
        }
      }
    }
  }
}
```

These traits are the Swift Package Manager equivalent of the `CapacitorFirebaseAuthentication/Google`, `CapacitorFirebaseAuthentication/Facebook` and `CapacitorFirebaseAuthentication/Lite` CocoaPods subspecs. Calling a sign-in method of a provider whose SDK is excluded rejects with an error.

**Attention**: SPM trait support requires Capacitor CLI **8.3.0+** and Xcode **16.3+** (Swift 6.1+).

## Configuration

These configuration values are available:

| Prop                 | Type       | Description                                                                                                                                                                                                                                                                                                    | Default | Since |
| -------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`authDomain`**     | `string`   | Configure the custom auth domain you want to use. Only available for Android and iOS.                                                                                                                                                                                                                          |         | 7.3.0 |
| **`skipNativeAuth`** | `boolean`  | Configure whether the plugin should skip the native authentication. Only needed if you want to use the Firebase JavaScript SDK. This configuration option has no effect on Firebase account linking. **Note that the plugin may behave differently across the platforms.** Only available for Android and iOS. | `false` | 0.1.0 |
| **`providers`**      | `string[]` | Configure the providers that should be loaded by the plugin. Possible values: `["apple.com", "facebook.com", "gc.apple.com", "github.com", "google.com", "microsoft.com", "playgames.google.com", "twitter.com", "yahoo.com", "phone"]` Only available for Android and iOS.                                    | `[]`    | 0.1.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "FirebaseAuthentication": {
      "authDomain": undefined,
      "skipNativeAuth": false,
      "providers": ["apple.com", "facebook.com"]
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capacitor-firebase/authentication" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseAuthentication: {
      authDomain: undefined,
      skipNativeAuth: false,
      providers: ["apple.com", "facebook.com"],
    },
  },
};

export default config;
```

## Firebase JavaScript SDK

[Here](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/firebase-js-sdk.md) 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-authentication-demo](https://github.com/robingenz/capacitor-firebase-authentication-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to sign in with email and password, social providers, a phone number, an email link, anonymously, and custom tokens, as well as how to manage the current user, reset passwords, verify and update email addresses, set the language, sign out, delete the user, and use the Firebase Emulator.

### Sign up and sign in with email and password

Create a new user account with email and password and sign the user in with those credentials:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const createUserWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
    email: 'mail@example.com',
    password: '1234',
  });
  return result.user;
};

const signInWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.signInWithEmailAndPassword({
    email: 'mail@example.com',
    password: '1234',
  });
  return result.user;
};
```

### Sign in with a social provider

Sign in users natively with providers such as Apple, Google, Facebook, GitHub, Microsoft, Twitter or Yahoo. Each provider requires the setup steps linked in the [Installation](#installation) section. Game Center sign-in is only available on iOS and Play Games sign-in is only available on Android:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInWithApple = async () => {
  const result = await FirebaseAuthentication.signInWithApple();
  return result.user;
};

const signInWithFacebook = async () => {
  const result = await FirebaseAuthentication.signInWithFacebook();
  return result.user;
};

const signInWithGameCenter = async () => {
  const result = await FirebaseAuthentication.signInWithGameCenter();
  return result.user;
};

const signInWithGithub = async () => {
  const result = await FirebaseAuthentication.signInWithGithub();
  return result.user;
};

const signInWithGoogle = async () => {
  const result = await FirebaseAuthentication.signInWithGoogle();
  return result.user;
};

const signInWithMicrosoft = async () => {
  const result = await FirebaseAuthentication.signInWithMicrosoft();
  return result.user;
};

const signInWithPlayGames = async () => {
  const result = await FirebaseAuthentication.signInWithPlayGames();
  return result.user;
};

const signInWithTwitter = async () => {
  const result = await FirebaseAuthentication.signInWithTwitter();
  return result.user;
};

const signInWithYahoo = async () => {
  const result = await FirebaseAuthentication.signInWithYahoo();
  return result.user;
};
```

### Sign in with a phone number

Start the phone number sign-in flow, which sends an SMS code to the user, and confirm the code with `confirmVerificationCode(...)`. Only available on Android and iOS:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInWithPhoneNumber = async () => {
  return new Promise(async resolve => {
    // Attach `phoneCodeSent` listener to be notified as soon as the SMS is sent
    await FirebaseAuthentication.addListener('phoneCodeSent', async event => {
      // Ask the user for the SMS code
      const verificationCode = window.prompt(
        'Please enter the verification code that was sent to your mobile device.',
      );
      // Confirm the verification code
      const result = await FirebaseAuthentication.confirmVerificationCode({
        verificationId: event.verificationId,
        verificationCode,
      });
      resolve(result.user);
    });
    // Attach `phoneVerificationCompleted` listener to be notified if phone verification could be finished automatically
    await FirebaseAuthentication.addListener(
      'phoneVerificationCompleted',
      async event => {
        resolve(event.result.user);
      },
    );
    // Start sign in with phone number and send the SMS
    await FirebaseAuthentication.signInWithPhoneNumber({
      phoneNumber: '123456789',
    });
  });
};
```

### Sign in with an email link

Send a passwordless sign-in link to the user's email address and complete the sign-in once the link is opened:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const sendSignInLinkToEmail = async () => {
  const email = 'mail@example.com';
  await FirebaseAuthentication.sendSignInLinkToEmail({
    email,
    actionCodeSettings: {
      // URL you want to redirect back to. The domain (www.example.com) for this
      // URL must be in the authorized domains list in the Firebase Console.
      url: 'https://www.example.com/finishSignUp?cartId=1234',
      // This must be true.
      handleCodeInApp: true,
      iOS: {
        bundleId: 'com.example.ios',
      },
      android: {
        packageName: 'com.example.android',
        installApp: true,
        minimumVersion: '12',
      },
      dynamicLinkDomain: 'example.page.link',
    },
  });
  // The link was successfully sent. Inform the user.
  // Save the email locally so you don't need to ask the user for it again
  // if they open the link on the same device.
  window.localStorage.setItem('emailForSignIn', email);
};

const signInWithEmailLink = async () => {
  // Get the email if available. This should be available if the user completes
  // the flow on the same device where they started it.
  const emailLink = window.location.href;
  // Confirm the link is a sign-in with email link.
  const { isSignInWithEmailLink } =
    await FirebaseAuthentication.isSignInWithEmailLink({
      emailLink,
    });
  if (!isSignInWithEmailLink) {
    return;
  }
  let email = window.localStorage.getItem('emailForSignIn');
  if (!email) {
    // User opened the link on a different device. To prevent session fixation
    // attacks, ask the user to provide the associated email again.
    email = window.prompt('Please provide your email for confirmation.');
  }
  // The client SDK will parse the code from the link for you.
  const result = await FirebaseAuthentication.signInWithEmailLink({
    email,
    emailLink,
  });
  // Clear email from storage.
  window.localStorage.removeItem('emailForSignIn');
  return result.user;
};
```

### Sign in anonymously

Sign in a user anonymously, for example to let users try your app before creating an account:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInAnonymously = async () => {
  const result = await FirebaseAuthentication.signInAnonymously();
  return result.user;
};
```

### Sign in with a custom token or OpenID Connect

Authenticate against your own backend with a custom token or use any OpenID Connect provider:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInWithCustomToken = async () => {
  const result = await FirebaseAuthentication.signInWithCustomToken({
    token: '1234',
  });
  return result.user;
};

const signInWithOpenIdConnect = async () => {
  const result = await FirebaseAuthentication.signInWithOpenIdConnect({
    providerId: 'oidc.example.com',
  });
  return result.user;
};
```

### Get the current user and ID token

Retrieve the currently signed-in user, their ID token, or the result of a pending authentication operation. The `getPendingAuthResult()` method is only available on Android:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const getCurrentUser = async () => {
  const result = await FirebaseAuthentication.getCurrentUser();
  return result.user;
};

const getIdToken = async () => {
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return;
  }
  const result = await FirebaseAuthentication.getIdToken();
  return result.token;
};

const getPendingAuthResult = async () => {
  const result = await FirebaseAuthentication.getPendingAuthResult();
  return result.user;
};
```

### Send and confirm a password reset

Send a password reset email to the user and confirm the password reset with the received out-of-band code:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const sendPasswordResetEmail = async () => {
  await FirebaseAuthentication.sendPasswordResetEmail({
    email: 'mail@example.com',
  });
};

const confirmPasswordReset = async () => {
  await FirebaseAuthentication.confirmPasswordReset({
    oobCode: '1234',
    newPassword: '4321',
  });
};
```

### Verify the user's email address

Send a verification email to the currently signed-in user and apply the received out-of-band code:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const sendEmailVerification = async () => {
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.sendEmailVerification();
};

const applyActionCode = async () => {
  await FirebaseAuthentication.applyActionCode({ oobCode: '1234' });
};
```

### Update the user's email or password

Update the email address or password of the currently signed-in user. With `verifyBeforeUpdateEmail(...)`, the new email address is verified before it is updated:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const updateEmail = async () => {
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updateEmail({
    newEmail: 'new.mail@example.com',
  });
};

const verifyBeforeUpdateEmail = async () => {
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.verifyBeforeUpdateEmail({
    newEmail: 'new.mail@example.com',
    actionCodeSettings: {
      url: 'https://www.example.com/cart?email=user@example.com&cartId=123',
      iOS: {
        bundleId: 'com.example.ios'
      },
      android: {
        packageName: 'com.example.android',
        installApp: true,
        minimumVersion: '12'
      },
      handleCodeInApp: true
    }
  });
};

const updatePassword = async () => {
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updatePassword({
    newPassword: '4321',
  });
};
```

### Look up sign-in methods for an email

Fetch the sign-in methods that are available for an email address:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const fetchSignInMethodsForEmail = async () => {
  const result = await FirebaseAuthentication.fetchSignInMethodsForEmail({
    email: 'mail@example.tld',
  });
  return result.signInMethods;
};
```

### Set the language

Set the language code to use, or apply the current app language:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const setLanguageCode = async () => {
  await FirebaseAuthentication.setLanguageCode({ languageCode: 'en-US' });
};

const useAppLanguage = async () => {
  await FirebaseAuthentication.useAppLanguage();
};
```

### Sign out and delete the user

Sign out the current user or permanently delete the user account:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signOut = async () => {
  await FirebaseAuthentication.signOut();
};

const deleteUser = async () => {
  await FirebaseAuthentication.deleteUser();
};
```

### Use the Firebase Emulator

Connect the plugin to a local [Firebase Emulator](https://firebase.google.com/docs/emulator-suite) instance during development:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const useEmulator = async () => {
  await FirebaseAuthentication.useEmulator({
    host: '10.0.2.2',
    port: 9099,
  });
};
```

## API

- [`applyActionCode(...)`](#applyactioncode)
- [`confirmPasswordReset(...)`](#confirmpasswordreset)
- [`confirmVerificationCode(...)`](#confirmverificationcode)
- [`createUserWithEmailAndPassword(...)`](#createuserwithemailandpassword)
- [`deleteUser()`](#deleteuser)
- [`fetchSignInMethodsForEmail(...)`](#fetchsigninmethodsforemail)
- [`getCurrentUser()`](#getcurrentuser)
- [`getPendingAuthResult()`](#getpendingauthresult)
- [`getIdToken(...)`](#getidtoken)
- [`getIdTokenResult(...)`](#getidtokenresult)
- [`getRedirectResult()`](#getredirectresult)
- [`getTenantId()`](#gettenantid)
- [`isSignInWithEmailLink(...)`](#issigninwithemaillink)
- [`linkWithApple(...)`](#linkwithapple)
- [`linkWithEmailAndPassword(...)`](#linkwithemailandpassword)
- [`linkWithEmailLink(...)`](#linkwithemaillink)
- [`linkWithFacebook(...)`](#linkwithfacebook)
- [`linkWithGameCenter(...)`](#linkwithgamecenter)
- [`linkWithGithub(...)`](#linkwithgithub)
- [`linkWithGoogle(...)`](#linkwithgoogle)
- [`linkWithMicrosoft(...)`](#linkwithmicrosoft)
- [`linkWithOpenIdConnect(...)`](#linkwithopenidconnect)
- [`linkWithPhoneNumber(...)`](#linkwithphonenumber)
- [`linkWithPlayGames(...)`](#linkwithplaygames)
- [`linkWithTwitter(...)`](#linkwithtwitter)
- [`linkWithYahoo(...)`](#linkwithyahoo)
- [`reload()`](#reload)
- [`revokeAccessToken(...)`](#revokeaccesstoken)
- [`sendEmailVerification(...)`](#sendemailverification)
- [`sendPasswordResetEmail(...)`](#sendpasswordresetemail)
- [`sendSignInLinkToEmail(...)`](#sendsigninlinktoemail)
- [`setLanguageCode(...)`](#setlanguagecode)
- [`setPersistence(...)`](#setpersistence)
- [`setTenantId(...)`](#settenantid)
- [`signInAnonymously()`](#signinanonymously)
- [`signInWithApple(...)`](#signinwithapple)
- [`signInWithCustomToken(...)`](#signinwithcustomtoken)
- [`signInWithEmailAndPassword(...)`](#signinwithemailandpassword)
- [`signInWithEmailLink(...)`](#signinwithemaillink)
- [`signInWithFacebook(...)`](#signinwithfacebook)
- [`signInWithGameCenter(...)`](#signinwithgamecenter)
- [`signInWithGithub(...)`](#signinwithgithub)
- [`signInWithGoogle(...)`](#signinwithgoogle)
- [`signInWithMicrosoft(...)`](#signinwithmicrosoft)
- [`signInWithOpenIdConnect(...)`](#signinwithopenidconnect)
- [`signInWithPhoneNumber(...)`](#signinwithphonenumber)
- [`signInWithPlayGames(...)`](#signinwithplaygames)
- [`signInWithTwitter(...)`](#signinwithtwitter)
- [`signInWithYahoo(...)`](#signinwithyahoo)
- [`signOut()`](#signout)
- [`unlink(...)`](#unlink)
- [`updateEmail(...)`](#updateemail)
- [`updatePassword(...)`](#updatepassword)
- [`updateProfile(...)`](#updateprofile)
- [`useAppLanguage()`](#useapplanguage)
- [`useEmulator(...)`](#useemulator)
- [`verifyBeforeUpdateEmail(...)`](#verifybeforeupdateemail)
- [`checkAppTrackingTransparencyPermission()`](#checkapptrackingtransparencypermission)
- [`requestAppTrackingTransparencyPermission()`](#requestapptrackingtransparencypermission)
- [`addListener('authStateChange', ...)`](#addlistenerauthstatechange-)
- [`addListener('idTokenChange', ...)`](#addlisteneridtokenchange-)
- [`addListener('phoneVerificationCompleted', ...)`](#addlistenerphoneverificationcompleted-)
- [`addListener('phoneVerificationFailed', ...)`](#addlistenerphoneverificationfailed-)
- [`addListener('phoneCodeSent', ...)`](#addlistenerphonecodesent-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### applyActionCode(...)

```
applyActionCode(options: ApplyActionCodeOptions) => Promise<void>
```

Applies a verification code sent to the user by email.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `ApplyActionCodeOptions` |

**Since:** 0.2.2

______________________________________________________________________

### confirmPasswordReset(...)

```
confirmPasswordReset(options: ConfirmPasswordResetOptions) => Promise<void>
```

Completes the password reset process.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `ConfirmPasswordResetOptions` |

**Since:** 0.2.2

______________________________________________________________________

### confirmVerificationCode(...)

```
confirmVerificationCode(options: ConfirmVerificationCodeOptions) => Promise<SignInResult>
```

Finishes the phone number verification process.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `ConfirmVerificationCodeOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 5.0.0

______________________________________________________________________

### createUserWithEmailAndPassword(...)

```
createUserWithEmailAndPassword(options: CreateUserWithEmailAndPasswordOptions) => Promise<SignInResult>
```

Creates a new user account with email and password. If the new account was created, the user is signed in automatically.

| Param         | Type                                    |
| ------------- | --------------------------------------- |
| **`options`** | `CreateUserWithEmailAndPasswordOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.2.2

______________________________________________________________________

### deleteUser()

```
deleteUser() => Promise<void>
```

Deletes and signs out the user.

**Since:** 1.3.0

______________________________________________________________________

### fetchSignInMethodsForEmail(...)

```
fetchSignInMethodsForEmail(options: FetchSignInMethodsForEmailOptions) => Promise<FetchSignInMethodsForEmailResult>
```

Fetches the sign-in methods for an email address.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `FetchSignInMethodsForEmailOptions` |

**Returns:** `Promise<FetchSignInMethodsForEmailResult>`

**Since:** 6.0.0

______________________________________________________________________

### getCurrentUser()

```
getCurrentUser() => Promise<GetCurrentUserResult>
```

Fetches the currently signed-in user.

**Returns:** `Promise<GetCurrentUserResult>`

**Since:** 0.1.0

______________________________________________________________________

### getPendingAuthResult()

```
getPendingAuthResult() => Promise<SignInResult>
```

Returns the [`SignInResult`](#signinresult) if your app launched a web sign-in flow and the OS cleans up the app while in the background.

Only available for Android.

**Returns:** `Promise<SignInResult>`

**Since:** 6.0.0

______________________________________________________________________

### getIdToken(...)

```
getIdToken(options?: GetIdTokenOptions | undefined) => Promise<GetIdTokenResult>
```

Fetches the Firebase Auth ID Token for the currently signed-in user.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `GetIdTokenOptions` |

**Returns:** `Promise<GetIdTokenResult>`

**Since:** 0.1.0

______________________________________________________________________

### getIdTokenResult(...)

```
getIdTokenResult(options?: GetIdTokenResultOptions | undefined) => Promise<GetIdTokenResultResult>
```

Returns a deserialized JSON Web Token (JWT) used to identify the user to a Firebase service.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `GetIdTokenResultOptions` |

**Returns:** `Promise<GetIdTokenResultResult>`

**Since:** 7.4.0

______________________________________________________________________

### getRedirectResult()

```
getRedirectResult() => Promise<SignInResult>
```

Returns the [`SignInResult`](#signinresult) from the redirect-based sign-in flow.

If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns a [`SignInResult`](#signinresult) with a null user.

Only available for Web.

**Returns:** `Promise<SignInResult>`

**Since:** 1.3.0

______________________________________________________________________

### getTenantId()

```
getTenantId() => Promise<GetTenantIdResult>
```

Get the tenant id.

**Returns:** `Promise<GetTenantIdResult>`

**Since:** 1.1.0

______________________________________________________________________

### isSignInWithEmailLink(...)

```
isSignInWithEmailLink(options: IsSignInWithEmailLinkOptions) => Promise<IsSignInWithEmailLinkResult>
```

Checks if an incoming link is a sign-in with email link suitable for `signInWithEmailLink`.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `IsSignInWithEmailLinkOptions` |

**Returns:** `Promise<IsSignInWithEmailLinkResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithApple(...)

```
linkWithApple(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Apple authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithEmailAndPassword(...)

```
linkWithEmailAndPassword(options: LinkWithEmailAndPasswordOptions) => Promise<LinkResult>
```

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                              |
| ------------- | --------------------------------- |
| **`options`** | `LinkWithEmailAndPasswordOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithEmailLink(...)

```
linkWithEmailLink(options: LinkWithEmailLinkOptions) => Promise<LinkResult>
```

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `LinkWithEmailLinkOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithFacebook(...)

```
linkWithFacebook(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Facebook authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithGameCenter(...)

```
linkWithGameCenter(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Game Center authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

Only available for iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.3.0

______________________________________________________________________

### linkWithGithub(...)

```
linkWithGithub(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with GitHub authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithGoogle(...)

```
linkWithGoogle(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Google authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithMicrosoft(...)

```
linkWithMicrosoft(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Microsoft authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithOpenIdConnect(...)

```
linkWithOpenIdConnect(options: LinkWithOpenIdConnectOptions) => Promise<LinkResult>
```

Links the user account with an OpenID Connect provider.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SignInWithOpenIdConnectOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 6.1.0

______________________________________________________________________

### linkWithPhoneNumber(...)

```
linkWithPhoneNumber(options: LinkWithPhoneNumberOptions) => Promise<void>
```

Links the user account with Phone Number authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

Use the `phoneVerificationCompleted` listener to be notified when the verification is completed. Use the `phoneVerificationFailed` listener to be notified when the verification is failed. Use the `phoneCodeSent` listener to get the verification id.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SignInWithPhoneNumberOptions` |

**Since:** 1.1.0

______________________________________________________________________

### linkWithPlayGames(...)

```
linkWithPlayGames(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Play Games authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

Only available for Android.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithTwitter(...)

```
linkWithTwitter(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Twitter authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### linkWithYahoo(...)

```
linkWithYahoo(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>
```

Links the user account with Yahoo authentication provider.

The user must be logged in on the native layer. The `skipNativeAuth` configuration option has no effect here.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### reload()

```
reload() => Promise<void>
```

Reloads user account data, if signed in.

**Since:** 1.3.0

______________________________________________________________________

### revokeAccessToken(...)

```
revokeAccessToken(options: RevokeAccessTokenOptions) => Promise<void>
```

Revokes the given access token. Currently only supports Apple OAuth access tokens.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `RevokeAccessTokenOptions` |

**Since:** 6.1.0

______________________________________________________________________

### sendEmailVerification(...)

```
sendEmailVerification(options?: SendEmailVerificationOptions | undefined) => Promise<void>
```

Sends a verification email to the currently signed in user.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SendEmailVerificationOptions` |

**Since:** 0.2.2

______________________________________________________________________

### sendPasswordResetEmail(...)

```
sendPasswordResetEmail(options: SendPasswordResetEmailOptions) => Promise<void>
```

Sends a password reset email.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `SendPasswordResetEmailOptions` |

**Since:** 0.2.2

______________________________________________________________________

### sendSignInLinkToEmail(...)

```
sendSignInLinkToEmail(options: SendSignInLinkToEmailOptions) => Promise<void>
```

Sends a sign-in email link to the user with the specified email.

To complete sign in with the email link, call `signInWithEmailLink` with the email address and the email link supplied in the email sent to the user.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SendSignInLinkToEmailOptions` |

**Since:** 1.1.0

______________________________________________________________________

### setLanguageCode(...)

```
setLanguageCode(options: SetLanguageCodeOptions) => Promise<void>
```

Sets the user-facing language code for auth operations.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SetLanguageCodeOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setPersistence(...)

```
setPersistence(options: SetPersistenceOptions) => Promise<void>
```

Sets the type of persistence for the currently saved auth session.

Only available for Web.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SetPersistenceOptions` |

**Since:** 5.2.0

______________________________________________________________________

### setTenantId(...)

```
setTenantId(options: SetTenantIdOptions) => Promise<void>
```

Sets the tenant id.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetTenantIdOptions` |

**Since:** 1.1.0

______________________________________________________________________

### signInAnonymously()

```
signInAnonymously() => Promise<SignInResult>
```

Signs in as an anonymous user.

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### signInWithApple(...)

```
signInWithApple(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the Apple sign-in flow.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithCustomToken(...)

```
signInWithCustomToken(options: SignInWithCustomTokenOptions) => Promise<SignInResult>
```

Starts the Custom Token sign-in flow.

This method cannot be used in combination with `skipNativeAuth` on Android and iOS. In this case you have to use the `signInWithCustomToken` interface of the Firebase JS SDK directly.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SignInWithCustomTokenOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithEmailAndPassword(...)

```
signInWithEmailAndPassword(options: SignInWithEmailAndPasswordOptions) => Promise<SignInResult>
```

Starts the sign-in flow using an email and password.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `SignInWithEmailAndPasswordOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.2.2

______________________________________________________________________

### signInWithEmailLink(...)

```
signInWithEmailLink(options: SignInWithEmailLinkOptions) => Promise<SignInResult>
```

Signs in using an email and sign-in email link.

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | `SignInWithEmailLinkOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 1.1.0

______________________________________________________________________

### signInWithFacebook(...)

```
signInWithFacebook(options?: SignInWithFacebookOptions | undefined) => Promise<SignInResult>
```

Starts the Facebook sign-in flow.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `SignInWithFacebookOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithGameCenter(...)

```
signInWithGameCenter(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>
```

Starts the Game Center sign-in flow.

Only available for iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | \`SignInWithOAuthOptions |

**Returns:** `Promise<SignInResult>`

**Since:** 1.3.0

______________________________________________________________________

### signInWithGithub(...)

```
signInWithGithub(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the GitHub sign-in flow.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithGoogle(...)

```
signInWithGoogle(options?: SignInWithGoogleOptions | undefined) => Promise<SignInResult>
```

Starts the Google sign-in flow.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SignInWithGoogleOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithMicrosoft(...)

```
signInWithMicrosoft(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the Microsoft sign-in flow.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithOpenIdConnect(...)

```
signInWithOpenIdConnect(options: SignInWithOpenIdConnectOptions) => Promise<SignInResult>
```

Starts the OpenID Connect sign-in flow.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SignInWithOpenIdConnectOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 6.1.0

______________________________________________________________________

### signInWithPhoneNumber(...)

```
signInWithPhoneNumber(options: SignInWithPhoneNumberOptions) => Promise<void>
```

Starts the sign-in flow using a phone number.

Use the `phoneVerificationCompleted` listener to be notified when the verification is completed. Use the `phoneVerificationFailed` listener to be notified when the verification is failed. Use the `phoneCodeSent` listener to get the verification id.

Only available for Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `SignInWithPhoneNumberOptions` |

**Since:** 0.1.0

______________________________________________________________________

### signInWithPlayGames(...)

```
signInWithPlayGames(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the Play Games sign-in flow.

Only available for Android.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithTwitter(...)

```
signInWithTwitter(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the Twitter sign-in flow.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signInWithYahoo(...)

```
signInWithYahoo(options?: SignInWithOAuthOptions | undefined) => Promise<SignInResult>
```

Starts the Yahoo sign-in flow.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `SignInWithOAuthOptions` |

**Returns:** `Promise<SignInResult>`

**Since:** 0.1.0

______________________________________________________________________

### signOut()

```
signOut() => Promise<void>
```

Starts the sign-out flow.

**Since:** 0.1.0

______________________________________________________________________

### unlink(...)

```
unlink(options: UnlinkOptions) => Promise<UnlinkResult>
```

Unlinks a provider from a user account.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `UnlinkOptions` |

**Returns:** `Promise<UnlinkResult>`

**Since:** 1.1.0

______________________________________________________________________

### updateEmail(...)

```
updateEmail(options: UpdateEmailOptions) => Promise<void>
```

Updates the email address of the currently signed in user.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UpdateEmailOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updatePassword(...)

```
updatePassword(options: UpdatePasswordOptions) => Promise<void>
```

Updates the password of the currently signed in user.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `UpdatePasswordOptions` |

**Since:** 0.1.0

______________________________________________________________________

### updateProfile(...)

```
updateProfile(options: UpdateProfileOptions) => Promise<void>
```

Updates a user's profile data.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `UpdateProfileOptions` |

**Since:** 1.3.0

______________________________________________________________________

### useAppLanguage()

```
useAppLanguage() => Promise<void>
```

Sets the user-facing language code to be the default app language.

**Since:** 0.1.0

______________________________________________________________________

### useEmulator(...)

```
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

Instrument your app to talk to the Authentication emulator.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UseEmulatorOptions` |

**Since:** 0.2.0

______________________________________________________________________

### verifyBeforeUpdateEmail(...)

```
verifyBeforeUpdateEmail(options: VerifyBeforeUpdateEmailOptions) => Promise<void>
```

Verifies the new email address before updating the email address of the currently signed in user.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `VerifyBeforeUpdateEmailOptions` |

**Since:** 6.3.0

______________________________________________________________________

### checkAppTrackingTransparencyPermission()

```
checkAppTrackingTransparencyPermission() => Promise<CheckAppTrackingTransparencyPermissionResult>
```

Checks the current status of app tracking transparency.

Only available on iOS.

**Returns:** `Promise<CheckAppTrackingTransparencyPermissionResult>`

**Since:** 7.2.0

______________________________________________________________________

### requestAppTrackingTransparencyPermission()

```
requestAppTrackingTransparencyPermission() => Promise<RequestAppTrackingTransparencyPermissionResult>
```

Opens the system dialog to authorize app tracking transparency.

**Attention:** The user may have disabled the tracking request in the device settings, see [Apple's documentation](https://support.apple.com/guide/iphone/iph4f4cbd242/ios).

Only available on iOS.

**Returns:** `Promise<CheckAppTrackingTransparencyPermissionResult>`

**Since:** 7.2.0

______________________________________________________________________

### addListener('authStateChange', ...)

```
addListener(eventName: 'authStateChange', listenerFunc: AuthStateChangeListener) => Promise<PluginListenerHandle>
```

Listen for the user's sign-in state changes.

**Attention:** This listener is not triggered when the `skipNativeAuth` is used. Use the Firebase JavaScript SDK instead.

| Param              | Type                      |
| ------------------ | ------------------------- |
| **`eventName`**    | `'authStateChange'`       |
| **`listenerFunc`** | `AuthStateChangeListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.1.0

______________________________________________________________________

### addListener('idTokenChange', ...)

```
addListener(eventName: 'idTokenChange', listenerFunc: IdTokenChangeListener) => Promise<PluginListenerHandle>
```

Listen to ID token changes for the currently signed-in user.

**Attention:** This listener is not triggered when the `skipNativeAuth` is used. Use the Firebase JavaScript SDK instead.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'idTokenChange'`       |
| **`listenerFunc`** | `IdTokenChangeListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.3.0

______________________________________________________________________

### addListener('phoneVerificationCompleted', ...)

```
addListener(eventName: 'phoneVerificationCompleted', listenerFunc: PhoneVerificationCompletedListener) => Promise<PluginListenerHandle>
```

Listen for a completed phone verification.

This listener only fires in two situations:

1. **Instant verification**: In some cases the phone number can be instantly verified without needing to send or enter a verification code.
1. **Auto-retrieval**: On some devices Google Play services can automatically detect the incoming verification SMS and perform verification without user action.

Only available for Android.

| Param              | Type                                 |
| ------------------ | ------------------------------------ |
| **`eventName`**    | `'phoneVerificationCompleted'`       |
| **`listenerFunc`** | `PhoneVerificationCompletedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 1.3.0

______________________________________________________________________

### addListener('phoneVerificationFailed', ...)

```
addListener(eventName: 'phoneVerificationFailed', listenerFunc: PhoneVerificationFailedListener) => Promise<PluginListenerHandle>
```

Listen for a failed phone verification.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'phoneVerificationFailed'`       |
| **`listenerFunc`** | `PhoneVerificationFailedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 1.3.0

______________________________________________________________________

### addListener('phoneCodeSent', ...)

```
addListener(eventName: 'phoneCodeSent', listenerFunc: PhoneCodeSentListener) => Promise<PluginListenerHandle>
```

Listen for a phone verification code.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'phoneCodeSent'`       |
| **`listenerFunc`** | `PhoneCodeSentListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 1.3.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### ApplyActionCodeOptions

| Prop          | Type     | Description                           | Since |
| ------------- | -------- | ------------------------------------- | ----- |
| **`oobCode`** | `string` | A verification code sent to the user. | 0.2.2 |

#### ConfirmPasswordResetOptions

| Prop              | Type     | Description                           | Since |
| ----------------- | -------- | ------------------------------------- | ----- |
| **`oobCode`**     | `string` | A verification code sent to the user. | 0.2.2 |
| **`newPassword`** | `string` | The new password.                     | 0.2.2 |

#### SignInResult

| Prop                     | Type                 | Description | Since                                                           |
| ------------------------ | -------------------- | ----------- | --------------------------------------------------------------- |
| **`user`**               | \`User               | null\`      | The currently signed-in user, or null if there isn't any.       |
| **`credential`**         | \`AuthCredential     | null\`      | Credentials returned by an auth provider.                       |
| **`additionalUserInfo`** | \`AdditionalUserInfo | null\`      | Additional user information from a federated identity provider. |

#### User

| Prop                | Type           | Description                                                          | Since |
| ------------------- | -------------- | -------------------------------------------------------------------- | ----- |
| **`displayName`**   | \`string       | null\`                                                               |       |
| **`email`**         | \`string       | null\`                                                               |       |
| **`emailVerified`** | `boolean`      |                                                                      | 0.1.0 |
| **`isAnonymous`**   | `boolean`      |                                                                      | 0.1.0 |
| **`metadata`**      | `UserMetadata` | The user's metadata.                                                 | 5.2.0 |
| **`phoneNumber`**   | \`string       | null\`                                                               |       |
| **`photoUrl`**      | \`string       | null\`                                                               |       |
| **`providerData`**  | `UserInfo[]`   | Additional per provider such as displayName and profile information. | 5.2.0 |
| **`providerId`**    | `string`       |                                                                      | 0.1.0 |
| **`tenantId`**      | \`string       | null\`                                                               |       |
| **`uid`**           | `string`       |                                                                      | 0.1.0 |

#### UserMetadata

| Prop                 | Type     | Description                                                   | Since |
| -------------------- | -------- | ------------------------------------------------------------- | ----- |
| **`creationTime`**   | `number` | Time the user was created in milliseconds since the epoch.    | 5.2.0 |
| **`lastSignInTime`** | `number` | Time the user last signed in in milliseconds since the epoch. | 5.2.0 |

#### UserInfo

| Prop              | Type     | Description                                 | Since                                                                                     |
| ----------------- | -------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **`displayName`** | \`string | null\`                                      | The display name of the user.                                                             |
| **`email`**       | \`string | null\`                                      | The email of the user.                                                                    |
| **`phoneNumber`** | \`string | null\`                                      | The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. |
| **`photoUrl`**    | \`string | null\`                                      | The profile photo URL of the user.                                                        |
| **`providerId`**  | `string` | The provider used to authenticate the user. | 5.2.0                                                                                     |
| **`uid`**         | `string` | The user's unique ID.                       | 5.2.0                                                                                     |

#### AuthCredential

| Prop                    | Type     | Description                                                                                                                              | Since |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`accessToken`**       | `string` | The OAuth access token associated with the credential if it belongs to an OAuth provider.                                                | 0.1.0 |
| **`authorizationCode`** | `string` | A token that the app uses to interact with the server. Only available for Apple Sign-in on iOS.                                          | 1.2.0 |
| **`idToken`**           | `string` | The OAuth ID token associated with the credential if it belongs to an OIDC provider.                                                     | 0.1.0 |
| **`nonce`**             | `string` | The random string used to make sure that the ID token you get was granted specifically in response to your app's authentication request. | 0.1.0 |
| **`providerId`**        | `string` | The authentication provider ID for the credential.                                                                                       | 0.1.0 |
| **`secret`**            | `string` | The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider.                                     | 0.1.0 |
| **`serverAuthCode`**    | `string` | The server auth code. Only available for Google Sign-in and Play Games Sign-In on Android and iOS.                                       | 5.2.0 |

#### AdditionalUserInfo

| Prop             | Type                          | Description                                                 | Since |
| ---------------- | ----------------------------- | ----------------------------------------------------------- | ----- |
| **`isNewUser`**  | `boolean`                     | Whether the user is new (sign-up) or existing (sign-in).    | 0.5.1 |
| **`profile`**    | `{ [key: string]: unknown; }` | Map containing IDP-specific user data.                      | 0.5.1 |
| **`providerId`** | `string`                      | Identifier for the provider used to authenticate this user. | 0.5.1 |
| **`username`**   | `string`                      | The username if the provider is GitHub or Twitter.          | 0.5.1 |

#### ConfirmVerificationCodeOptions

| Prop                   | Type     | Description                                                                                                                                        | Since |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`verificationId`**   | `string` | The verification ID received from the `phoneCodeSent` listener. The `verificationCode` option must also be provided.                               | 5.0.0 |
| **`verificationCode`** | `string` | The verification code either received from the `phoneCodeSent` listener or entered by the user. The `verificationId` option must also be provided. | 5.0.0 |

#### CreateUserWithEmailAndPasswordOptions

| Prop           | Type     | Since |
| -------------- | -------- | ----- |
| **`email`**    | `string` | 0.2.2 |
| **`password`** | `string` | 0.2.2 |

#### FetchSignInMethodsForEmailResult

| Prop                | Type       | Description                                                                                                                                                                                                                                                                                     | Since |
| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`signInMethods`** | `string[]` | The sign-in methods for the specified email address. This list is empty when [Email Enumeration Protection](https://cloud.google.com/identity-platform/docs/admin/email-enumeration-protection) is enabled, irrespective of the number of authentication methods available for the given email. | 6.0.0 |

#### FetchSignInMethodsForEmailOptions

| Prop        | Type     | Description               | Since |
| ----------- | -------- | ------------------------- | ----- |
| **`email`** | `string` | The user's email address. | 6.0.0 |

#### GetCurrentUserResult

| Prop       | Type   | Description | Since                                                     |
| ---------- | ------ | ----------- | --------------------------------------------------------- |
| **`user`** | \`User | null\`      | The currently signed-in user, or null if there isn't any. |

#### GetIdTokenResult

| Prop        | Type     | Description                            | Since |
| ----------- | -------- | -------------------------------------- | ----- |
| **`token`** | `string` | The Firebase Auth ID token JWT string. | 0.1.0 |

#### GetIdTokenOptions

| Prop               | Type      | Description                                   | Since |
| ------------------ | --------- | --------------------------------------------- | ----- |
| **`forceRefresh`** | `boolean` | Force refresh regardless of token expiration. | 0.1.0 |

#### GetIdTokenResultResult

| Prop                     | Type                      | Description                                                                                                                                            | Since                                                                                                                      |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **`authTime`**           | `number`                  | The authentication time in milliseconds since the epoch. This is the time the user authenticated (signed in) and not the time the token was refreshed. | 7.4.0                                                                                                                      |
| **`expirationTime`**     | `number`                  | The ID token expiration time in milliseconds since the epoch.                                                                                          | 7.4.0                                                                                                                      |
| **`issuedAtTime`**       | `number`                  | The ID token issuance time in milliseconds since the epoch.                                                                                            | 7.4.0                                                                                                                      |
| **`signInProvider`**     | \`string                  | null\`                                                                                                                                                 | The sign-in provider through which the ID token was obtained.                                                              |
| **`signInSecondFactor`** | \`string                  | null\`                                                                                                                                                 | The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). |
| **`claims`**             | `Record<string, unknown>` | The entire payload claims of the ID token including the standard reserved claims as well as the custom claims.                                         | 7.4.0                                                                                                                      |

#### GetIdTokenResultOptions

| Prop               | Type      | Description                                   | Since |
| ------------------ | --------- | --------------------------------------------- | ----- |
| **`forceRefresh`** | `boolean` | Force refresh regardless of token expiration. | 7.4.0 |

#### GetTenantIdResult

| Prop           | Type     | Description | Since                                           |
| -------------- | -------- | ----------- | ----------------------------------------------- |
| **`tenantId`** | \`string | null\`      | The tenant id. `null` if it has never been set. |

#### IsSignInWithEmailLinkResult

| Prop                        | Type      | Description                                                                                   |
| --------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| **`isSignInWithEmailLink`** | `boolean` | Whether an incoming link is a signup with email link suitable for `signInWithEmailLink(...)`. |

#### IsSignInWithEmailLinkOptions

| Prop            | Type     | Description                                | Since |
| --------------- | -------- | ------------------------------------------ | ----- |
| **`emailLink`** | `string` | The link sent to the user's email address. | 1.1.0 |

#### SignInWithOAuthOptions

| Prop                   | Type                      | Description                                                                                                                                                                                                                                                                                             | Default                                                                                                                                                                                                                               | Since     |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **`customParameters`** | `SignInCustomParameter[]` | Configures custom parameters to be passed to the identity provider during the OAuth sign-in flow. Supports Apple, Facebook, GitHub, Google, Microsoft, Twitter and Yahoo on Web. Supports Apple, GitHub, Microsoft, Twitter and Yahoo on Android. Supports GitHub, Microsoft, Twitter and Yahoo on iOS. |                                                                                                                                                                                                                                       | 1.1.0     |
| **`mode`**             | \`'popup'                 | 'redirect'\`                                                                                                                                                                                                                                                                                            | Whether to use the popup-based OAuth authentication flow or the full-page redirect flow. If you choose `redirect`, you will get the result of the call via the `authStateChange` listener after the redirect. Only available for Web. | `'popup'` |
| **`scopes`**           | `string[]`                | Scopes to request from provider. Supports Apple, Facebook, GitHub, Google, Microsoft, Twitter and Yahoo on Web. Supports Apple, GitHub, Google, Microsoft, Twitter, Yahoo and Play Games on Android. Supports Facebook, GitHub, Google, Microsoft, Twitter and Yahoo on iOS.                            |                                                                                                                                                                                                                                       | 1.1.0     |

#### SignInCustomParameter

| Prop        | Type     | Description                                                        | Since |
| ----------- | -------- | ------------------------------------------------------------------ | ----- |
| **`key`**   | `string` | The custom parameter key (e.g. `login_hint`).                      | 0.1.0 |
| **`value`** | `string` | The custom parameter value (e.g. `user@firstadd.onmicrosoft.com`). | 0.1.0 |

#### LinkWithEmailAndPasswordOptions

| Prop           | Type     | Description               | Since |
| -------------- | -------- | ------------------------- | ----- |
| **`email`**    | `string` | The user's email address. | 1.1.0 |
| **`password`** | `string` | The user's password.      | 1.1.0 |

#### LinkWithEmailLinkOptions

| Prop            | Type     | Description                                | Since |
| --------------- | -------- | ------------------------------------------ | ----- |
| **`email`**     | `string` | The user's email address.                  | 1.1.0 |
| **`emailLink`** | `string` | The link sent to the user's email address. | 1.1.0 |

#### SignInWithOpenIdConnectOptions

| Prop             | Type     | Description                     | Since |
| ---------------- | -------- | ------------------------------- | ----- |
| **`providerId`** | `string` | The OpenID Connect provider ID. | 6.1.0 |

#### SignInWithPhoneNumberOptions

| Prop                    | Type      | Description                                                                                                                                                   | Default | Since |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`phoneNumber`**       | `string`  | The phone number to be verified in E.164 format.                                                                                                              |         | 0.1.0 |
| **`recaptchaVerifier`** | `unknown` | The reCAPTCHA verifier. Must be an instance of `firebase.auth.RecaptchaVerifier`. Only available for Web.                                                     |         | 5.2.0 |
| **`resendCode`**        | `boolean` | Resend the verification code to the specified phone number. `signInWithPhoneNumber` must be called once before using this option. Only available for Android. | `false` | 1.3.0 |
| **`timeout`**           | `number`  | The maximum amount of time in seconds to wait for the SMS auto-retrieval. Use 0 to disable SMS-auto-retrieval. Only available for Android.                    | `60`    | 5.4.0 |

#### RevokeAccessTokenOptions

| Prop        | Type     | Description                 | Since |
| ----------- | -------- | --------------------------- | ----- |
| **`token`** | `string` | The access token to revoke. | 6.1.0 |

#### SendEmailVerificationOptions

| Prop                     | Type                 | Description                                                                                               | Since |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`actionCodeSettings`** | `ActionCodeSettings` | Structure that contains the required continue/state URL with optional Android and iOS bundle identifiers. | 6.1.0 |

#### ActionCodeSettings

An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers.

| Prop                  | Type                                                                      | Description                                                                                                                                                                                                                                                                     | Since |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`android`**         | `{ installApp?: boolean; minimumVersion?: string; packageName: string; }` | Sets the Android package name.                                                                                                                                                                                                                                                  |       |
| **`handleCodeInApp`** | `boolean`                                                                 | When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed.                                                                                                                                      |       |
| **`iOS`**             | `{ bundleId: string; }`                                                   | Sets the iOS bundle ID.                                                                                                                                                                                                                                                         |       |
| **`url`**             | `string`                                                                  | Sets the link continue/state URL.                                                                                                                                                                                                                                               |       |
| **`linkDomain`**      | `string`                                                                  | When multiple custom Firebase Hosting link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`). The domain must be configured in Firebase Hosting and owned by the project. | 7.1.0 |

#### SendPasswordResetEmailOptions

| Prop                     | Type                 | Description                                                                                               | Since |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`email`**              | `string`             |                                                                                                           | 0.2.2 |
| **`actionCodeSettings`** | `ActionCodeSettings` | Structure that contains the required continue/state URL with optional Android and iOS bundle identifiers. | 6.1.0 |

#### SendSignInLinkToEmailOptions

| Prop                     | Type                 | Description                                                                                               | Since |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------- | ----- |
| **`email`**              | `string`             | The user's email address.                                                                                 | 1.1.0 |
| **`actionCodeSettings`** | `ActionCodeSettings` | Structure that contains the required continue/state URL with optional Android and iOS bundle identifiers. | 1.1.0 |

#### SetLanguageCodeOptions

| Prop               | Type     | Description           | Since |
| ------------------ | -------- | --------------------- | ----- |
| **`languageCode`** | `string` | BCP 47 language code. | 0.1.0 |

#### SetPersistenceOptions

| Prop              | Type          | Description            | Since |
| ----------------- | ------------- | ---------------------- | ----- |
| **`persistence`** | `Persistence` | The persistence types. | 5.2.0 |

#### SetTenantIdOptions

| Prop           | Type     | Description    | Since |
| -------------- | -------- | -------------- | ----- |
| **`tenantId`** | `string` | The tenant id. | 1.1.0 |

#### SignInWithCustomTokenOptions

| Prop        | Type     | Description                       | Since |
| ----------- | -------- | --------------------------------- | ----- |
| **`token`** | `string` | The custom token to sign in with. | 0.1.0 |

#### SignInWithEmailAndPasswordOptions

| Prop           | Type     | Description               | Since |
| -------------- | -------- | ------------------------- | ----- |
| **`email`**    | `string` | The user's email address. | 0.2.2 |
| **`password`** | `string` | The user's password.      | 0.2.2 |

#### SignInWithEmailLinkOptions

| Prop            | Type     | Description                                | Since |
| --------------- | -------- | ------------------------------------------ | ----- |
| **`email`**     | `string` | The user's email address.                  | 1.1.0 |
| **`emailLink`** | `string` | The link sent to the user's email address. | 1.1.0 |

#### SignInWithFacebookOptions

| Prop                  | Type      | Description                                                                                                                                                                                                                                                                                                                                                           | Default | Since |
| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`useLimitedLogin`** | `boolean` | Whether to use the Facebook Limited Login mode. If set to `true`, no access token will be returned but the user does not have to grant App Tracking Transparency permission. If set to `false`, the user has to grant App Tracking Transparency permission. You can request the permission with `requestAppTrackingTransparencyPermission()`. Only available for iOS. | `false` | 7.2.0 |

#### SignInOptions

| Prop                 | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Since |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`skipNativeAuth`** | `boolean` | Whether the plugin should skip the native authentication or not. Only needed if you want to use the Firebase JavaScript SDK. This value overwrites the configrations value of the `skipNativeAuth` option. If no value is set, the configuration value is used. **Note that the plugin may behave differently across the platforms.** `skipNativeAuth` cannot be used in combination with `signInWithCustomToken`, `createUserWithEmailAndPassword` or `signInWithEmailAndPassword`. Only available for Android and iOS. | 1.1.0 |

#### SignInWithGoogleOptions

| Prop                       | Type      | Description                                                                       | Default | Since |
| -------------------------- | --------- | --------------------------------------------------------------------------------- | ------- | ----- |
| **`useCredentialManager`** | `boolean` | Whether to use the Credential Manager API to sign in. Only available for Android. | `true`  | 7.2.0 |

#### UnlinkResult

| Prop       | Type   | Description | Since                                                     |
| ---------- | ------ | ----------- | --------------------------------------------------------- |
| **`user`** | \`User | null\`      | The currently signed-in user, or null if there isn't any. |

#### UnlinkOptions

| Prop             | Type         | Description             | Since |
| ---------------- | ------------ | ----------------------- | ----- |
| **`providerId`** | `ProviderId` | The provider to unlink. | 1.1.0 |

#### UpdateEmailOptions

| Prop           | Type     | Description            | Since |
| -------------- | -------- | ---------------------- | ----- |
| **`newEmail`** | `string` | The new email address. | 0.2.2 |

#### UpdatePasswordOptions

| Prop              | Type     | Description       | Since |
| ----------------- | -------- | ----------------- | ----- |
| **`newPassword`** | `string` | The new password. | 0.2.2 |

#### UpdateProfileOptions

| Prop              | Type     | Description | Since                    |
| ----------------- | -------- | ----------- | ------------------------ |
| **`displayName`** | \`string | null\`      | The user's display name. |
| **`photoUrl`**    | \`string | null\`      | The user's photo URL.    |

#### UseEmulatorOptions

| Prop         | Type     | Description                                   | Default  | Since |
| ------------ | -------- | --------------------------------------------- | -------- | ----- |
| **`host`**   | `string` | The emulator host without any port or scheme. |          | 0.2.0 |
| **`port`**   | `number` | The emulator port.                            | `9099`   | 0.2.0 |
| **`scheme`** | `string` | The emulator scheme. Only available for Web.  | `"http"` | 5.2.0 |

#### VerifyBeforeUpdateEmailOptions

| Prop                     | Type                 | Description                                         | Since |
| ------------------------ | -------------------- | --------------------------------------------------- | ----- |
| **`newEmail`**           | `string`             | The new email address to be verified before update. | 6.3.0 |
| **`actionCodeSettings`** | `ActionCodeSettings` | The action code settings                            | 6.3.0 |

#### CheckAppTrackingTransparencyPermissionResult

| Prop         | Type                                     | Description                                         | Since |
| ------------ | ---------------------------------------- | --------------------------------------------------- | ----- |
| **`status`** | `AppTrackingTransparencyPermissionState` | The permission status of App Tracking Transparency. | 7.2.0 |

#### PluginListenerHandle

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

#### AuthStateChange

| Prop       | Type   | Description | Since                                                     |
| ---------- | ------ | ----------- | --------------------------------------------------------- |
| **`user`** | \`User | null\`      | The currently signed-in user, or null if there isn't any. |

#### PhoneVerificationCompletedEvent

| Prop                   | Type     | Description                                                                                                       | Since |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`verificationCode`** | `string` | The verification code sent to the user's phone number. If instant verification is used, this property is not set. | 5.0.0 |

#### PhoneVerificationFailedEvent

| Prop          | Type     | Description                                                                     | Since |
| ------------- | -------- | ------------------------------------------------------------------------------- | ----- |
| **`message`** | `string` | The error message.                                                              | 1.3.0 |
| **`code`**    | `string` | The error code. Only available if the error is a Firebase Authentication error. | 8.6.0 |

#### PhoneCodeSentEvent

| Prop                 | Type     | Description                                                             | Since |
| -------------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`verificationId`** | `string` | The verification ID, which is needed to identify the verification code. | 1.3.0 |

### Type Aliases

#### LinkWithOAuthOptions

`SignInWithOAuthOptions`

#### LinkResult

`SignInResult`

#### LinkWithOpenIdConnectOptions

`SignInWithOpenIdConnectOptions`

#### LinkWithPhoneNumberOptions

`SignInWithPhoneNumberOptions`

#### AppTrackingTransparencyPermissionState

`PermissionState | 'restricted'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### RequestAppTrackingTransparencyPermissionResult

`CheckAppTrackingTransparencyPermissionResult`

#### AuthStateChangeListener

Callback to receive the user's sign-in state change notifications.

`(change: AuthStateChange): void`

#### IdTokenChangeListener

Callback to receive the ID token change notifications.

`(change: GetIdTokenResult): void`

#### PhoneVerificationCompletedListener

Callback to receive the verification code sent to the user's phone number.

`(event: PhoneVerificationCompletedEvent): void`

#### PhoneVerificationFailedListener

Callback to receive notifications of failed phone verification.

`(event: PhoneVerificationFailedEvent): void`

#### PhoneCodeSentListener

Callback to receive the verification ID.

`(event: PhoneCodeSentEvent): void`

### Enums

#### Persistence

| Members              | Value                | Description                                  | Since |
| -------------------- | -------------------- | -------------------------------------------- | ----- |
| **`IndexedDbLocal`** | `'INDEXED_DB_LOCAL'` | Long term persistence using IndexedDB.       | 5.2.0 |
| **`InMemory`**       | `'IN_MEMORY'`        | No persistence.                              | 5.2.0 |
| **`BrowserLocal`**   | `'BROWSER_LOCAL'`    | Long term persistence using local storage.   | 5.2.0 |
| **`BrowserSession`** | `'BROWSER_SESSION'`  | Temporary persistence using session storage. | 5.2.0 |

#### ProviderId

| Members           | Value                    |
| ----------------- | ------------------------ |
| **`APPLE`**       | `'apple.com'`            |
| **`FACEBOOK`**    | `'facebook.com'`         |
| **`GAME_CENTER`** | `'gc.apple.com'`         |
| **`GITHUB`**      | `'github.com'`           |
| **`GOOGLE`**      | `'google.com'`           |
| **`MICROSOFT`**   | `'microsoft.com'`        |
| **`PLAY_GAMES`**  | `'playgames.google.com'` |
| **`TWITTER`**     | `'twitter.com'`          |
| **`YAHOO`**       | `'yahoo.com'`            |
| **`PASSWORD`**    | `'password'`             |
| **`PHONE`**       | `'phone'`                |

## FAQ

### What does this plugin do?

This plugin enables the use of [Firebase Authentication](https://firebase.google.com/docs/auth) in a Capacitor app. It uses the Firebase SDK for [Java](https://firebase.google.com/docs/reference/android) (Android), [Swift](https://firebase.google.com/docs/reference/swift) (iOS) and [JavaScript](https://firebase.google.com/docs/reference/js).

### What is the difference between the web implementation of this plugin and the Firebase JS SDK?

The web implementation of this plugin encapsulates the Firebase JS SDK and enables a consistent interface across all platforms. You can decide if you prefer to use the web implementation or the Firebase JS SDK.

### What is the difference between the native and web authentication?

For web authentication, the Firebase JS SDK is used. This only works to a limited extent on Android and iOS in the WebViews (see [here](https://developers.googleblog.com/2016/08/modernizing-oauth-interactions-in-native-apps.html)). For native authentication, the native SDKs from Firebase, Google, etc. are used. These offer all the functionalities that the Firebase JS SDK also offers on the web. However, after a login with the native SDK, the user is only logged in on the native layer of the app. If the user should also be logged in on the web layer (for example to access Cloud Firestore via Firebase JS SDK), additional steps are required (see [here](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/firebase-js-sdk.md)).

### How can I use this plugin with the Firebase JavaScript SDK?

See [here](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/docs/firebase-js-sdk.md).

### Which sign-in methods are supported?

The plugin supports native sign-in with Apple, Facebook, Game Center, GitHub, Google, Microsoft, OpenID Connect, Play Games, Twitter, and Yahoo, as well as anonymous sign-in, email link sign-in, email and password authentication, phone number sign-in, and custom token sign-in. The required setup steps for each sign-in method are linked in the [Installation](#installation) section.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase App Check](https://capawesome.io/docs/sdks/capacitor/firebase/app-check/): Unofficial Capacitor plugin for Firebase App Check.
- [Firebase Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/): Unofficial Capacitor plugin for Firebase Cloud Firestore.
- [Firebase Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/): Unofficial Capacitor plugin for Firebase Cloud Messaging.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/authentication/LICENSE).

## Credits

This plugin is based on the [Capacitor Firebase Authentication](https://github.com/robingenz/capacitor-firebase-authentication) plugin. Thanks to everyone who contributed to the project!

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Cloud Firestore Plugin

Unofficial Capacitor plugin for [Firebase Cloud Firestore](https://firebase.google.com/docs/firestore/).[1](#fn:1)

## Use Cases

The Cloud Firestore plugin is typically used to store and sync app data in the cloud, for example:

- **Real-time updates**: Keep your UI up to date by listening to document and collection changes with snapshot listeners.
- **User-generated content**: Create, read, update, and delete documents for user profiles, posts, or other app data.
- **Complex queries**: Filter and sort collections with composite filters and query constraints such as `where`, `orderBy`, and `limit`.
- **Offline support**: Enable offline persistence and control network access to work with locally cached data.
- **Atomic writes**: Perform multiple write operations as a single atomic batch with `writeBatch(...)`.

## 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     |

## Guides

- [Announcing the Capacitor Firebase Cloud Firestore Plugin](https://capawesome.io/blog/announcing-the-capacitor-firebase-cloud-firestore-plugin/)
- [Capacitor Firestore: Real-Time Data & Offline Sync](https://capawesome.io/blog/capacitor-firebase-cloud-firestore-guide/): Real-time listeners, offline persistence, and atomic writes with this plugin.
- [How to Wrap an Angular App with Capacitor and Firebase](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/): Uses this plugin alongside Cloud Storage to store and sync user data.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): How the database combines with Authentication, Storage, and the rest of the family in a real app.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/firestore` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/firestore
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

#### 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:

- `$firebaseFirestoreVersion` version of `com.google.firebase:firebase-firestore` (default: `26.0.2`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/firestore": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

These configuration values are available:

| Prop             | Type     | Description                                                                           | Since |
| ---------------- | -------- | ------------------------------------------------------------------------------------- | ----- |
| **`databaseId`** | `string` | The database ID of the Firestore database to use. Only available for Android and iOS. | 8.2.0 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "FirebaseFirestore": {
      "databaseId": undefined
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capacitor-firebase/firestore" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseFirestore: {
      databaseId: undefined,
    },
  },
};

export default config;
```

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to create, read, update, and delete documents, update documents with field values, perform batched writes, query collections, control network access, use the Firebase Emulator, and listen for and remove real-time updates.

### Create a document

Add a new document to a collection with an auto-generated ID, or write a document at a known reference with `setDocument(...)`. Set `merge` to `true` to merge the data with an existing document:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocument = async () => {
  await FirebaseFirestore.addDocument({
    reference: 'users',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const setDocument = async () => {
  await FirebaseFirestore.setDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
    merge: true,
  });
};
```

### Read a document

Read a single document by its reference:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getDocument = async () => {
  const { snapshot } = await FirebaseFirestore.getDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
  return snapshot;
};
```

### Update or delete a document

Update fields of an existing document or delete it entirely:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocument = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const deleteDocument = async () => {
  await FirebaseFirestore.deleteDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
};
```

### Update a document with field values

Use `FieldValue` helpers to increment numbers, set server timestamps, modify arrays, or delete fields:

```
import { FieldValue, FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocumentWithFieldValue = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: {
      born: FieldValue.increment(1),
      updatedAt: FieldValue.serverTimestamp(),
      nicknames: FieldValue.arrayUnion('Prof'),
      tags: FieldValue.arrayRemove('draft'),
      deprecatedField: FieldValue.delete(),
    },
  });
};
```

### Perform a batched write

Execute multiple set, update, and delete operations as a single atomic batch:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'update',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};
```

### Query a collection

Read multiple documents from a collection or a collection group. You can filter the results with a composite filter and apply query constraints such as `orderBy` and `limit`:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getCollection = async () => {
  const { snapshots } = await FirebaseFirestore.getCollection({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

const getCollectionGroup = async () => {
  const { snapshots } = await FirebaseFirestore.getCollectionGroup({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};
```

### Control network access

Disable and re-enable the use of the network, for example to force the plugin to work with locally cached data:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const enableNetwork = async () => {
  await FirebaseFirestore.enableNetwork();
};

const disableNetwork = async () => {
  await FirebaseFirestore.disableNetwork();
};
```

### Use the Firebase Emulator

Connect the plugin to a local [Firebase Emulator](https://firebase.google.com/docs/emulator-suite) instance during development:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const useEmulator = async () => {
  await FirebaseFirestore.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};
```

### Listen for real-time updates

Attach snapshot listeners to a document, a collection, or a collection group to get notified whenever the data changes:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocumentSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
    {
      reference: 'users/Aorq09lkt1ynbR7xhTUx',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionGroupSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};
```

### Remove listeners

Remove a single snapshot listener by its callback ID or remove all listeners at once:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

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

## API

- [`addDocument(...)`](#adddocument)
- [`addCollectionGroupSnapshotListener(...)`](#addcollectiongroupsnapshotlistener)
- [`addCollectionSnapshotListener(...)`](#addcollectionsnapshotlistener)
- [`addDocumentSnapshotListener(...)`](#adddocumentsnapshotlistener)
- [`clearPersistence()`](#clearpersistence)
- [`deleteDocument(...)`](#deletedocument)
- [`disableNetwork()`](#disablenetwork)
- [`disablePersistence()`](#disablepersistence)
- [`enablePersistence(...)`](#enablepersistence)
- [`enableNetwork()`](#enablenetwork)
- [`getCollection(...)`](#getcollection)
- [`getCollectionGroup(...)`](#getcollectiongroup)
- [`getCountFromServer(...)`](#getcountfromserver)
- [`getDocument(...)`](#getdocument)
- [`removeAllListeners()`](#removealllisteners)
- [`removeSnapshotListener(...)`](#removesnapshotlistener)
- [`setDocument(...)`](#setdocument)
- [`updateDocument(...)`](#updatedocument)
- [`useEmulator(...)`](#useemulator)
- [`writeBatch(...)`](#writebatch)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### addDocument(...)

```
addDocument(options: AddDocumentOptions) => Promise<AddDocumentResult>
```

Adds a new document to a collection with the given data.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `AddDocumentOptions` |

**Returns:** `Promise<AddDocumentResult>`

**Since:** 5.2.0

______________________________________________________________________

### addCollectionGroupSnapshotListener(...)

```
addCollectionGroupSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback<T>) => Promise<CallbackId>
```

Adds a listener for collection group snapshot events.

| Param          | Type                                            |
| -------------- | ----------------------------------------------- |
| **`options`**  | `AddCollectionGroupSnapshotListenerOptions`     |
| **`callback`** | `AddCollectionGroupSnapshotListenerCallback<T>` |

**Returns:** `Promise<string>`

**Since:** 6.1.0

______________________________________________________________________

### addCollectionSnapshotListener(...)

```
addCollectionSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback<T>) => Promise<CallbackId>
```

Adds a listener for collection snapshot events.

| Param          | Type                                       |
| -------------- | ------------------------------------------ |
| **`options`**  | `AddCollectionSnapshotListenerOptions`     |
| **`callback`** | `AddCollectionSnapshotListenerCallback<T>` |

**Returns:** `Promise<string>`

**Since:** 5.2.0

______________________________________________________________________

### addDocumentSnapshotListener(...)

```
addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>
```

Adds a listener for document snapshot events.

| Param          | Type                                     |
| -------------- | ---------------------------------------- |
| **`options`**  | `AddDocumentSnapshotListenerOptions`     |
| **`callback`** | `AddDocumentSnapshotListenerCallback<T>` |

**Returns:** `Promise<string>`

**Since:** 5.2.0

______________________________________________________________________

### clearPersistence()

```
clearPersistence() => Promise<void>
```

Clears the persistent storage. This includes pending writes and cached documents.

**Attention**: Must be called after the app is shutdown or when the app is first initialized.

**Since:** 5.2.0

______________________________________________________________________

### deleteDocument(...)

```
deleteDocument(options: DeleteDocumentOptions) => Promise<void>
```

Deletes the document referred to by the specified reference.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `DeleteDocumentOptions` |

**Since:** 5.2.0

______________________________________________________________________

### disableNetwork()

```
disableNetwork() => Promise<void>
```

Disables use of the network.

**Since:** 5.2.0

______________________________________________________________________

### disablePersistence()

```
disablePersistence() => Promise<void>
```

Disables offline persistence.

**Attention**: Must be called before any other Firestore method.

**Since:** 8.2.0

______________________________________________________________________

### enablePersistence(...)

```
enablePersistence(options?: EnablePersistenceOptions | undefined) => Promise<void>
```

Enables offline persistence.

**Attention**: Must be called before any other Firestore method.

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `EnablePersistenceOptions` |

**Since:** 8.2.0

______________________________________________________________________

### enableNetwork()

```
enableNetwork() => Promise<void>
```

Re-enables use of the network.

**Since:** 5.2.0

______________________________________________________________________

### getCollection(...)

```
getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>
```

Reads the collection referenced by the specified reference.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `GetCollectionOptions` |

**Returns:** `Promise<GetCollectionResult<T>>`

**Since:** 5.2.0

______________________________________________________________________

### getCollectionGroup(...)

```
getCollectionGroup<T extends DocumentData = DocumentData>(options: GetCollectionGroupOptions) => Promise<GetCollectionGroupResult<T>>
```

Reads the collection group referenced by the specified reference.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `GetCollectionGroupOptions` |

**Returns:** `Promise<GetCollectionGroupResult<T>>`

______________________________________________________________________

### getCountFromServer(...)

```
getCountFromServer(options: GetCountFromServerOptions) => Promise<GetCountFromServerResult>
```

Fetches the number of documents in a collection.

| Param         | Type                        |
| ------------- | --------------------------- |
| **`options`** | `GetCountFromServerOptions` |

**Returns:** `Promise<GetCountFromServerResult>`

**Since:** 6.4.0

______________________________________________________________________

### getDocument(...)

```
getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>
```

Reads the document referred to by the specified reference.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetDocumentOptions` |

**Returns:** `Promise<GetDocumentResult<T>>`

**Since:** 5.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 5.2.0

______________________________________________________________________

### removeSnapshotListener(...)

```
removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise<void>
```

Remove a listener for document or collection snapshot events.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `RemoveSnapshotListenerOptions` |

**Since:** 5.2.0

______________________________________________________________________

### setDocument(...)

```
setDocument(options: SetDocumentOptions) => Promise<void>
```

Writes to the document referred to by the specified reference. If the document does not yet exist, it will be created.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetDocumentOptions` |

**Since:** 5.2.0

______________________________________________________________________

### updateDocument(...)

```
updateDocument(options: UpdateDocumentOptions) => Promise<void>
```

Updates fields in the document referred to by the specified reference.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `UpdateDocumentOptions` |

**Since:** 5.2.0

______________________________________________________________________

### useEmulator(...)

```
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

Instrument your app to talk to the Firestore emulator.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UseEmulatorOptions` |

**Since:** 6.1.0

______________________________________________________________________

### writeBatch(...)

```
writeBatch(options: WriteBatchOptions) => Promise<void>
```

Execute multiple write operations as a single batch.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `WriteBatchOptions` |

**Since:** 6.1.0

______________________________________________________________________

### Interfaces

#### AddDocumentResult

| Prop            | Type                | Description                                | Since |
| --------------- | ------------------- | ------------------------------------------ | ----- |
| **`reference`** | `DocumentReference` | The reference of the newly added document. | 5.2.0 |

#### AddDocumentOptions

| Prop            | Type           | Description                                                                         | Since |
| --------------- | -------------- | ----------------------------------------------------------------------------------- | ----- |
| **`reference`** | `string`       | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 |
| **`data`**      | `DocumentData` | An object containing the data for the new document.                                 | 5.2.0 |

#### DocumentData

#### AddCollectionGroupSnapshotListenerOptions

| Prop                   | Type                             | Description                                                                                         | Since |
| ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`reference`**        | `string`                         | The reference as a string, with path components separated by a forward slash (`/`).                 | 6.1.0 |
| **`compositeFilter`**  | `QueryCompositeFilterConstraint` | The filter to apply.                                                                                | 6.1.0 |
| **`queryConstraints`** | `QueryNonFilterConstraint[]`     | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 6.1.0 |

#### QueryCompositeFilterConstraint

| Prop                   | Type                      | Description           | Since                       |
| ---------------------- | ------------------------- | --------------------- | --------------------------- |
| **`type`**             | \`'and'                   | 'or'\`                | The type of the constraint. |
| **`queryConstraints`** | `QueryFilterConstraint[]` | The filters to apply. | 5.2.0                       |

#### QueryFieldFilterConstraint

| Prop            | Type            | Description                    | Since |
| --------------- | --------------- | ------------------------------ | ----- |
| **`type`**      | `'where'`       | The type of the constraint.    | 5.2.0 |
| **`fieldPath`** | `string`        | The path to compare.           | 5.2.0 |
| **`opStr`**     | `QueryOperator` | The operation string to apply. | 5.2.0 |
| **`value`**     | `any`           | The value for comparison.      | 5.2.0 |

#### QueryOrderByConstraint

| Prop               | Type               | Description                 | Since |
| ------------------ | ------------------ | --------------------------- | ----- |
| **`type`**         | `'orderBy'`        | The type of the constraint. | 5.2.0 |
| **`fieldPath`**    | `string`           | The path to compare.        | 5.2.0 |
| **`directionStr`** | `OrderByDirection` | The direction to sort by.   | 5.2.0 |

#### QueryLimitConstraint

| Prop        | Type      | Description                            | Since                       |
| ----------- | --------- | -------------------------------------- | --------------------------- |
| **`type`**  | \`'limit' | 'limitToLast'\`                        | The type of the constraint. |
| **`limit`** | `number`  | The maximum number of items to return. | 5.2.0                       |

#### QueryStartAtConstraint

| Prop            | Type        | Description                                                                                                                                                        | Since                       |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| **`type`**      | \`'startAt' | 'startAfter'\`                                                                                                                                                     | The type of the constraint. |
| **`reference`** | `string`    | The reference to start at or after as a string, with path components separated by a forward slash (`/`). **Attention**: This requires an additional document read. | 5.2.0                       |

#### QueryEndAtConstraint

| Prop            | Type      | Description                                                                                                                                                          | Since                       |
| --------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **`type`**      | \`'endAt' | 'endBefore'\`                                                                                                                                                        | The type of the constraint. |
| **`reference`** | `string`  | The reference as to end at or before as a string, with path components separated by a forward slash (`/`). **Attention**: This requires an additional document read. | 5.2.0                       |

#### GetCollectionGroupResult

| Prop            | Type                    | Description                      | Since |
| --------------- | ----------------------- | -------------------------------- | ----- |
| **`snapshots`** | `DocumentSnapshot<T>[]` | The documents in the collection. | 5.2.0 |

#### DocumentSnapshot

| Prop           | Type               | Description                                                                           | Since                                                                                         |
| -------------- | ------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **`id`**       | `string`           | The document's identifier within its collection.                                      | 5.2.0                                                                                         |
| **`path`**     | `string`           | The path of the document.                                                             | 5.2.0                                                                                         |
| **`data`**     | \`T                | null\`                                                                                | An object containing the data for the document. Returns `null` if the document doesn't exist. |
| **`metadata`** | `SnapshotMetadata` | Metadata about the snapshot, concerning its source and if it has local modifications. | 6.2.0                                                                                         |

#### SnapshotMetadata

| Prop                   | Type      | Description                                               | Since |
| ---------------------- | --------- | --------------------------------------------------------- | ----- |
| **`fromCache`**        | `boolean` | True if the snapshot was created from cached data.        | 6.2.0 |
| **`hasPendingWrites`** | `boolean` | True if the snapshot was created from pending write data. | 6.2.0 |

#### AddCollectionSnapshotListenerOptions

| Prop                   | Type                             | Description                                                                                         | Since |
| ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`reference`**        | `string`                         | The reference as a string, with path components separated by a forward slash (`/`).                 | 5.2.0 |
| **`compositeFilter`**  | `QueryCompositeFilterConstraint` | The filter to apply.                                                                                | 5.2.0 |
| **`queryConstraints`** | `QueryNonFilterConstraint[]`     | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

#### GetCollectionResult

| Prop            | Type                    | Description                      | Since |
| --------------- | ----------------------- | -------------------------------- | ----- |
| **`snapshots`** | `DocumentSnapshot<T>[]` | The documents in the collection. | 5.2.0 |

#### AddDocumentSnapshotListenerOptions

| Prop            | Type     | Description                                                                         | Since |
| --------------- | -------- | ----------------------------------------------------------------------------------- | ----- |
| **`reference`** | `string` | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 |

#### GetDocumentResult

| Prop           | Type                  | Description                    | Since |
| -------------- | --------------------- | ------------------------------ | ----- |
| **`snapshot`** | `DocumentSnapshot<T>` | The current document contents. | 5.2.0 |

#### DeleteDocumentOptions

| Prop            | Type     | Description                                                                         | Since |
| --------------- | -------- | ----------------------------------------------------------------------------------- | ----- |
| **`reference`** | `string` | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 |

#### EnablePersistenceOptions

| Prop                  | Type      | Description                                                                      | Default              | Since |
| --------------------- | --------- | -------------------------------------------------------------------------------- | -------------------- | ----- |
| **`cacheSizeBytes`**  | `number`  | The cache size in bytes.                                                         | `104857600 (100 MB)` | 8.2.0 |
| **`synchronizeTabs`** | `boolean` | Whether to synchronize persistence across multiple tabs. Only available for Web. | `false`              | 8.2.0 |

#### GetCollectionOptions

| Prop                   | Type                             | Description                                                                                         | Since |
| ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`reference`**        | `string`                         | The reference as a string, with path components separated by a forward slash (`/`).                 | 5.2.0 |
| **`compositeFilter`**  | `QueryCompositeFilterConstraint` | The filter to apply.                                                                                | 5.2.0 |
| **`queryConstraints`** | `QueryNonFilterConstraint[]`     | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

#### GetCollectionGroupOptions

| Prop                   | Type                             | Description                                                                                         | Since |
| ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`reference`**        | `string`                         | The reference as a string, with path components separated by a forward slash (`/`).                 | 5.2.0 |
| **`compositeFilter`**  | `QueryCompositeFilterConstraint` | The filter to apply.                                                                                | 5.2.0 |
| **`queryConstraints`** | `QueryNonFilterConstraint[]`     | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

#### GetCountFromServerResult

| Prop        | Type     | Description                                | Since |
| ----------- | -------- | ------------------------------------------ | ----- |
| **`count`** | `number` | The number of documents in the collection. | 6.4.0 |

#### GetCountFromServerOptions

| Prop                   | Type                             | Description                                                                                      | Since |
| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ | ----- |
| **`reference`**        | `string`                         | The reference as a string, with path components separated by a forward slash (`/`).              | 6.4.0 |
| **`compositeFilter`**  | `QueryCompositeFilterConstraint` | The filter to apply.                                                                             | 8.3.0 |
| **`queryConstraints`** | `QueryNonFilterConstraint[]`     | Narrow or order the set of documents to count, but do not explicitly filter for document fields. | 8.3.0 |

#### GetDocumentOptions

| Prop            | Type     | Description                                                                         | Since |
| --------------- | -------- | ----------------------------------------------------------------------------------- | ----- |
| **`reference`** | `string` | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 |

#### RemoveSnapshotListenerOptions

| Prop             | Type         | Since |
| ---------------- | ------------ | ----- |
| **`callbackId`** | `CallbackId` | 5.2.0 |

#### SetDocumentOptions

| Prop            | Type           | Description                                                                         | Default | Since |
| --------------- | -------------- | ----------------------------------------------------------------------------------- | ------- | ----- |
| **`reference`** | `string`       | The reference as a string, with path components separated by a forward slash (`/`). |         | 5.2.0 |
| **`data`**      | `DocumentData` | An object containing the data for the new document.                                 |         | 5.2.0 |
| **`merge`**     | `boolean`      | Whether to merge the provided data with an existing document.                       | `false` | 5.2.0 |

#### UpdateDocumentOptions

| Prop            | Type           | Description                                                                         | Since |
| --------------- | -------------- | ----------------------------------------------------------------------------------- | ----- |
| **`reference`** | `string`       | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 |
| **`data`**      | `DocumentData` | An object containing the data for the new document.                                 | 5.2.0 |

#### UseEmulatorOptions

| Prop       | Type     | Description                                                                                                                                                                     | Default | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`host`** | `string` | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. |         | 6.1.0 |
| **`port`** | `number` | The emulator port.                                                                                                                                                              | `8080`  | 6.1.0 |

#### WriteBatchOptions

| Prop             | Type                    | Description                             | Since |
| ---------------- | ----------------------- | --------------------------------------- | ----- |
| **`operations`** | `WriteBatchOperation[]` | The operations to execute in the batch. | 6.1.0 |

#### WriteBatchOperation

| Prop            | Type           | Description                                                                         | Since      |
| --------------- | -------------- | ----------------------------------------------------------------------------------- | ---------- |
| **`type`**      | \`'set'        | 'update'                                                                            | 'delete'\` |
| **`reference`** | `string`       | The reference as a string, with path components separated by a forward slash (`/`). | 6.1.0      |
| **`data`**      | `DocumentData` | An object containing the data for the new document.                                 | 6.1.0      |
| **`options`**   | `SetOptions`   | An object to configure the set behavior.                                            | 7.3.0      |

#### SetOptions

| Prop        | Type      | Description                                                                | Default | Since |
| ----------- | --------- | -------------------------------------------------------------------------- | ------- | ----- |
| **`merge`** | `boolean` | Whether a merge should be performed or the document should be overwritten. | `false` | 7.3.0 |

### Type Aliases

#### QueryFilterConstraint

`QueryFieldFilterConstraint | QueryCompositeFilterConstraint`

#### QueryOperator

`'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'`

#### QueryNonFilterConstraint

`QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint`

#### OrderByDirection

`'desc' | 'asc'`

#### AddCollectionGroupSnapshotListenerCallback

`(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void`

#### AddCollectionGroupSnapshotListenerCallbackEvent

`GetCollectionGroupResult<T>`

#### CallbackId

`string`

#### AddCollectionSnapshotListenerCallback

`(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void`

#### AddCollectionSnapshotListenerCallbackEvent

`GetCollectionResult<T>`

#### AddDocumentSnapshotListenerCallback

`(event: AddDocumentSnapshotListenerCallbackEvent<T> | null, error: any): void`

#### AddDocumentSnapshotListenerCallbackEvent

`GetDocumentResult<T>`

## FAQ

### How do I get notified about data changes in real time?

Attach a snapshot listener with `addDocumentSnapshotListener(...)`, `addCollectionSnapshotListener(...)`, or `addCollectionGroupSnapshotListener(...)`. The callback is invoked whenever the observed data changes. Each listener returns a callback ID that you can later pass to `removeSnapshotListener(...)`, or you can remove all listeners at once with `removeAllListeners()`. See [Listen for real-time updates](#listen-for-real-time-updates) for an example.

### What is the difference between `getCollection` and `getCollectionGroup`?

The `getCollection(...)` method reads the documents of a single collection at the given reference. The `getCollectionGroup(...)` method reads the documents of a collection group, which consists of all collections with the same ID. Both methods support composite filters and query constraints.

### Does the plugin work offline?

Yes, you can enable offline persistence with the `enablePersistence(...)` method, which must be called before any other Firestore method. You can also disable and re-enable the use of the network with `disableNetwork()` and `enableNetwork()`. The persistent storage, including pending writes and cached documents, can be cleared with `clearPersistence()`, which must be called after the app is shut down or when it is first initialized.

### Can I use a Firestore database other than the default one?

Yes, you can set the `databaseId` configuration option in your Capacitor configuration to select the Firestore database to use (see [Configuration](#configuration)). This option is only available on Android and iOS.

### How do I test my app against a local Firestore instance?

Use the `useEmulator(...)` method to connect the plugin to a local Firebase Emulator instance by providing its host and port. This allows you to develop and test without touching your production data.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Unofficial Capacitor plugin for Firebase Authentication.
- [Firebase Cloud Functions](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/): Unofficial Capacitor plugin for Firebase Cloud Functions.
- [Firebase Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/): Unofficial Capacitor plugin for Firebase Cloud Storage.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Cloud Functions Plugin

Unofficial Capacitor plugin for [Firebase Cloud Functions](https://firebase.google.com/docs/functions/).[1](#fn:1)

## Use Cases

The Firebase Cloud Functions plugin is typically used to run backend logic from your Capacitor app without managing your own server, for example:

- **Serverless backend logic**: Call callable Cloud Functions by name to run trusted server-side code from your app.
- **Structured data exchange**: Pass strings, numbers, booleans, arrays, and objects to a function and process the returned result.
- **Custom domains and regions**: Call functions that are deployed in a specific region or hosted on a custom domain by their URL.
- **Local development**: Test your functions against the Cloud Functions emulator before deploying them to production.

## Compatibility

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

## Guides

- [Call Firebase Cloud Functions from a Capacitor App](https://capawesome.io/blog/capacitor-firebase-cloud-functions-guide/): Call serverless backend logic by name or URL, including local emulator testing, with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): Which plugins pair naturally with your backend logic, from sign-in to the database it reads.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/functions` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/functions
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://firebase.google.com/docs/android/setup) / [iOS](https://firebase.google.com/docs/ios/setup)).

### Android

#### 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:

- `$firebaseFunctionsVersion` version of `com.google.firebase:firebase-functions` (default: `22.1.0`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/functions": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Usage

The following examples show how to call Cloud Functions by name or by URL and how to connect to the Cloud Functions emulator.

### Call a function by name

Call a callable Cloud Function by its name. You can pass strings, numbers, booleans, arrays, and objects as data and receive the result of the function in the `data` property. Use the `region` option if your function is not deployed in the default region:

```
import { FirebaseFunctions } from '@capacitor-firebase/functions';

const callByName = async () => {
    const { data } = await FirebaseFunctions.callByName({
        name: 'helloWorld',
        data: {
            string: 'Hello World!',
            number: 123,
            boolean: true,
            array: [1, 2, 3],
            object: {
                key: 'value'
            }
        }
    });
    return data;
};
```

### Call a function by URL

If your callable function is hosted on a custom domain or you prefer to address it directly, call it by its URL:

```
import { FirebaseFunctions } from '@capacitor-firebase/functions';

const callByUrl = async () => {
    const { data } = await FirebaseFunctions.callByUrl({
        url: 'https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net/helloWorld',
        data: {
            string: 'Hello World!',
            number: 123,
            boolean: true,
            array: [1, 2, 3],
            object: {
                key: 'value'
            }
        }
    });
    return data;
};
```

### Use the Cloud Functions emulator

During development, you can instrument your app to talk to the local Cloud Functions emulator. When using an Android emulator device, `10.0.2.2` is the special IP address to connect to the `localhost` of the host computer. Note that on Android, the cleartext traffic must be allowed, which is not intended for use in production:

```
import { FirebaseFunctions } from '@capacitor-firebase/functions';

const useEmulator = async () => {
  await FirebaseFunctions.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};
```

## API

- [`callByName(...)`](#callbyname)
- [`callByUrl(...)`](#callbyurl)
- [`useEmulator(...)`](#useemulator)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### callByName(...)

```
callByName<RequestData = unknown, ResponseData = unknown>(options: CallByNameOptions<RequestData>) => Promise<CallByNameResult<ResponseData>>
```

Call a callable function by name.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `CallByNameOptions<RequestData>` |

**Returns:** `Promise<CallByNameResult<ResponseData>>`

**Since:** 6.1.0

______________________________________________________________________

### callByUrl(...)

```
callByUrl<RequestData = unknown, ResponseData = unknown>(options: CallByUrlOptions<RequestData>) => Promise<CallByUrlResult<ResponseData>>
```

Call a callable function by URL.

| Param         | Type                            |
| ------------- | ------------------------------- |
| **`options`** | `CallByUrlOptions<RequestData>` |

**Returns:** `Promise<CallByUrlResult<ResponseData>>`

**Since:** 6.1.0

______________________________________________________________________

### useEmulator(...)

```
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

Instrument your app to talk to the Cloud Functions emulator.

On Android, the cleartext traffic must be allowed. On the Capacitor configuration:

```
{
  server: {
    cleartext: true
  }
}
```

**The cleartext traffic is not intended for use in production.**

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UseEmulatorOptions` |

**Since:** 6.1.0

______________________________________________________________________

### Interfaces

#### CallResult

| Prop       | Type           | Description                          | Since |
| ---------- | -------------- | ------------------------------------ | ----- |
| **`data`** | `ResponseData` | The result of the callable function. | 6.1.0 |

#### CallByNameOptions

| Prop         | Type     | Description                          | Since |
| ------------ | -------- | ------------------------------------ | ----- |
| **`name`**   | `string` | The name of the callable function.   | 6.1.0 |
| **`region`** | `string` | The region of the callable function. | 6.1.0 |

#### CallByUrlOptions

| Prop      | Type     | Description                       | Since |
| --------- | -------- | --------------------------------- | ----- |
| **`url`** | `string` | The URL of the callable function. | 6.1.0 |

#### UseEmulatorOptions

| Prop                       | Type     | Description                                                                                                                                                                     | Default | Since |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`host`**                 | `string` | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. |         | 6.1.0 |
| **`port`**                 | `number` | The emulator port.                                                                                                                                                              | `5001`  | 6.1.0 |
| **`regionOrCustomDomain`** | `string` | The region the callable functions are located in or a custom domain hosting the callable functions.                                                                             |         |       |

### Type Aliases

#### CallByNameResult

`CallResult<ResponseData>`

#### CallByUrlResult

`CallResult<ResponseData>`

## FAQ

### What is the difference between `callByName` and `callByUrl`?

The `callByName(...)` method calls a callable function by its name and, optionally, its region. The `callByUrl(...)` method calls a callable function by its full URL instead, which is useful if the function is hosted on a custom domain.

### What data types can I pass to a callable function?

You can pass strings, numbers, booleans, arrays, and nested objects as data to a callable function. The result of the function is returned in the `data` property of the call result.

### How do I test my functions locally?

Use the `useEmulator(...)` method to instrument your app to talk to the local Cloud Functions emulator, as shown in the [usage example](#use-the-cloud-functions-emulator) above. When testing on an Android emulator device, use `10.0.2.2` as the host to reach the `localhost` of the host computer. Keep in mind that on Android, the cleartext traffic must be allowed for this, which is not intended for use in production.

### Why do I get a SwiftPM package identity collision on iOS?

This is a known issue when using the plugin with Swift Package Manager. Add the `symlink` package option for `@capacitor-firebase/functions` to your Capacitor configuration as described in the [Installation](#installation) section. Note that SPM `packageOptions` support requires Capacitor CLI 8.4.0 or later.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Sign in users with Firebase Authentication.
- [Firebase Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/): Store and sync app data in Cloud Firestore.
- [Firebase Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/): Upload and download files with Firebase Cloud Storage.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/functions/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/functions/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Cloud Messaging Plugin

Unofficial Capacitor plugin for [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).[1](#fn:1)

## Use Cases

The Firebase Cloud Messaging plugin is typically used to engage and re-engage users with push notifications, for example:

- **Push notifications**: Notify users about new content, messages, or offers, even when the app is not in the foreground.
- **Topic-based messaging**: Let users subscribe to topics such as news categories and send a message to all subscribers of a topic at once.
- **Device targeting**: Retrieve the FCM token of a device to send push messages to specific users or devices.
- **Background data sync**: Receive data push notifications in the background to keep the content of your app up to date.
- **Notification management**: List, remove, or clear the notifications that are visible on the notifications screen.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [The Push Notifications Guide for Capacitor](https://capawesome.io/blog/capacitor-push-notifications-guide/)
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): From push notifications to analytics and crash reporting — every Firebase plugin in one guide.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/messaging` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/messaging firebase
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

#### 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:

- `$firebaseMessagingVersion` version of `com.google.firebase:firebase-messaging` (default: `25.0.1`)

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

#### Push Notification Icon

The Push Notification icon with the appropriate name should be added to the `android/app/src/main/AndroidManifest.xml` file:

```
<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/push_icon_name" />
```

If no icon is specified, Android uses the application icon, but the push icon should be white pixels on a transparent background. Since the application icon does not usually look like this, it shows a white square or circle. Therefore, it is recommended to provide a separate icon for push notifications.

#### Prevent auto initialization

When a registration token is generated, the library uploads the identifier and configuration data to Firebase. If you prefer to prevent token autogeneration, disable Analytics collection and FCM auto initialization by adding these metadata values to the `android/app/src/main/AndroidManifest.xml` file:

```
<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />
```

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/messaging": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

#### Setup

> **Important**: Make sure that no other Capacitor Push Notification plugin is installed (see [here](https://github.com/capawesome-team/capacitor-firebase/pull/267#issuecomment-1328885820)).

See [Prerequisites](https://capacitorjs.com/docs/guides/push-notifications-firebase#prerequisites) and complete the prerequisites first.

See [Upload the APNS Certificate or Key to Firebase](https://capacitorjs.com/docs/guides/push-notifications-firebase#upload-the-apns-certificate-or-key-to-firebase) and follow the instructions to upload the APNS Certificate or APNS Auth Key to Firebase.

> If you have difficulties with the instructions, you can also look at the corresponding sections of [this guide](https://capawesome.io/blog/capacitor-push-notifications-guide/#ios).

Add the following to your app's `AppDelegate.swift`:

```
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name.init("didReceiveRemoteNotification"), object: completionHandler, userInfo: userInfo)
}
```

**Attention**: If you use this plugin in combination with `@capacitor-firebase/authentication`, then add the following to your app's `AppDelegate.swift`:

```
+ import FirebaseAuth

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    if Auth.auth().canHandle(url) {
+      return true
+    }
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}
```

#### Prevent auto initialization

When a registration token is generated, the library uploads the identifier and configuration data to Firebase. If you prefer to prevent token autogeneration, disable FCM auto initialization by editing your `ios/App/App/Info.plist` and set `FirebaseMessagingAutoInitEnabled` key to `NO`.

### Web

1. See [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with) and follow the instructions to configure your web credentials correctly.
1. Add a `firebase-messaging-sw.js` file to the root of your domain. This file can be empty if you do not want to receive push notifications in the background. See [Setting notification options in the service worker](https://firebase.google.com/docs/cloud-messaging/js/receive#setting_notification_options_in_the_service_worker) for more information.

## Configuration

On iOS you can configure the way the push notifications are displayed when the app is in foreground.

| Prop                      | Type                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Default                       | Since |
| ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- |
| **`presentationOptions`** | `PresentationOption[]` | This is an array of strings you can combine. Possible values in the array are: - `badge`: badge count on the app icon is updated (default value) - `sound`: the device will ring/vibrate when the push notification is received - `alert`: the push notification is displayed in a native dialog - `criticalAlert`: the push notification is displayed in a native dialog and bypasses the mute switch An empty array can be provided if none of the options are desired. Only available for iOS. | `["alert", "badge", "sound"]` | 0.2.2 |

### Examples

In `capacitor.config.json`:

```
{
  "plugins": {
    "FirebaseMessaging": {
      "presentationOptions": ["alert", "badge", "sound"]
    }
  }
}
```

In `capacitor.config.ts`:

```
/// <reference types="@capacitor-firebase/messaging" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseMessaging: {
      presentationOptions: ["alert", "badge", "sound"],
    },
  },
};

export default config;
```

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to check and request notification permissions, manage the FCM token, listen for incoming notifications and their actions, subscribe to topics, and manage delivered notifications.

### Check and request permissions

Check and request the permission to receive push notifications. On Android, these methods only need to be called on Android 13+:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const checkPermissions = async () => {
  const result = await FirebaseMessaging.checkPermissions();
  return result.receive;
};

const requestPermissions = async () => {
  const result = await FirebaseMessaging.requestPermissions();
  return result.receive;
};
```

### Retrieve or delete the FCM token

Register the app to receive push notifications and retrieve the FCM token that can be used to send push messages to the device. Delete the token, for example when a user signs out, to stop receiving push notifications. You can also be notified when a new token is received using the `tokenReceived` event, which is only available on Android and iOS:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const getToken = async () => {
  const result = await FirebaseMessaging.getToken();
  return result.token;
};

const deleteToken = async () => {
  await FirebaseMessaging.deleteToken();
};

const addTokenReceivedListener = async () => {
  await FirebaseMessaging.addListener('tokenReceived', event => {
    console.log('tokenReceived', { event });
  });
};
```

### Listen for incoming push notifications

Be notified when a push notification is received. If the app is in the background, this listener is only called for data push notifications on Android and for silent push notifications on iOS:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const addNotificationReceivedListener = async () => {
  await FirebaseMessaging.addListener('notificationReceived', event => {
    console.log('notificationReceived', { event });
  });
};
```

### React to notification actions

Be notified when an action is performed on a push notification, for example when the user taps on it. Only available on Android and iOS:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const addNotificationActionPerformedListener = async () => {
  await FirebaseMessaging.addListener('notificationActionPerformed', event => {
    console.log('notificationActionPerformed', { event });
  });
};
```

### Subscribe to topics

Subscribe to or unsubscribe from a topic to receive push messages that are sent to that topic. Only available on Android and iOS:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const subscribeToTopic = async () => {
  await FirebaseMessaging.subscribeToTopic({ topic: 'news' });
};

const unsubscribeFromTopic = async () => {
  await FirebaseMessaging.unsubscribeFromTopic({ topic: 'news' });
};
```

### Manage delivered notifications

Get, remove, or clear the notifications that are currently visible on the notifications screen:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const getDeliveredNotifications = async () => {
  const result = await FirebaseMessaging.getDeliveredNotifications();
  return result.notifications;
};

const removeDeliveredNotifications = async () => {
  await FirebaseMessaging.removeDeliveredNotifications({
    notifications: [
      {
        id: '798dfhliblqew89pzads',
      },
    ],
  });
};

const removeAllDeliveredNotifications = async () => {
  await FirebaseMessaging.removeAllDeliveredNotifications();
};
```

### Remove all listeners

Remove all listeners that have been added for this plugin:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

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

## API

- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`isSupported()`](#issupported)
- [`getToken(...)`](#gettoken)
- [`deleteToken()`](#deletetoken)
- [`getDeliveredNotifications()`](#getdeliverednotifications)
- [`removeDeliveredNotifications(...)`](#removedeliverednotifications)
- [`removeAllDeliveredNotifications()`](#removealldeliverednotifications)
- [`subscribeToTopic(...)`](#subscribetotopic)
- [`unsubscribeFromTopic(...)`](#unsubscribefromtopic)
- [`createChannel(...)`](#createchannel)
- [`deleteChannel(...)`](#deletechannel)
- [`listChannels()`](#listchannels)
- [`addListener('tokenReceived', ...)`](#addlistenertokenreceived-)
- [`addListener('notificationReceived', ...)`](#addlistenernotificationreceived-)
- [`addListener('notificationActionPerformed', ...)`](#addlistenernotificationactionperformed-)
- [`addListener('apnsTokenReceived', ...)`](#addlistenerapnstokenreceived-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check permission to receive push notifications.

On **Android**, this method only needs to be called on Android 13+.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.2.2

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request permission to receive push notifications.

On **Android**, this method only needs to be called on Android 13+.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.2.2

______________________________________________________________________

### isSupported()

```
isSupported() => Promise<IsSupportedResult>
```

Checks if all required APIs exist.

Always returns `true` on Android and iOS.

**Returns:** `Promise<IsSupportedResult>`

**Since:** 0.3.1

______________________________________________________________________

### getToken(...)

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

Register the app to receive push notifications. Returns a FCM token that can be used to send push messages to that Messaging instance.

This method also re-enables FCM auto-init.

| Param         | Type              |
| ------------- | ----------------- |
| **`options`** | `GetTokenOptions` |

**Returns:** `Promise<GetTokenResult>`

**Since:** 0.2.2

______________________________________________________________________

### deleteToken()

```
deleteToken() => Promise<void>
```

Delete the FCM token and unregister the app to stop receiving push notifications. Can be called, for example, when a user signs out.

**Since:** 0.2.2

______________________________________________________________________

### getDeliveredNotifications()

```
getDeliveredNotifications() => Promise<GetDeliveredNotificationsResult>
```

Get a list of notifications that are visible on the notifications screen.

Note: This will return all delivered notifications, including local notifications, and not just FCM notifications.

On Android, the data field of the FCM notification will NOT be included.

**Returns:** `Promise<GetDeliveredNotificationsResult>`

**Since:** 0.2.2

______________________________________________________________________

### removeDeliveredNotifications(...)

```
removeDeliveredNotifications(options: RemoveDeliveredNotificationsOptions) => Promise<void>
```

Remove specific notifications from the notifications screen.

| Param         | Type                                  |
| ------------- | ------------------------------------- |
| **`options`** | `RemoveDeliveredNotificationsOptions` |

**Since:** 0.2.2

______________________________________________________________________

### removeAllDeliveredNotifications()

```
removeAllDeliveredNotifications() => Promise<void>
```

Remove all notifications from the notifications screen.

Note: This will remove all delivered notifications, including local notifications, and not just FCM notifications.

**Since:** 0.2.2

______________________________________________________________________

### subscribeToTopic(...)

```
subscribeToTopic(options: SubscribeToTopicOptions) => Promise<void>
```

Subscribes to topic in the background.

Only available for Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SubscribeToTopicOptions` |

**Since:** 0.2.2

______________________________________________________________________

### unsubscribeFromTopic(...)

```
unsubscribeFromTopic(options: UnsubscribeFromTopicOptions) => Promise<void>
```

Unsubscribes from topic in the background.

Only available for Android and iOS.

| Param         | Type                          |
| ------------- | ----------------------------- |
| **`options`** | `UnsubscribeFromTopicOptions` |

**Since:** 0.2.2

______________________________________________________________________

### createChannel(...)

```
createChannel(options: CreateChannelOptions) => Promise<void>
```

Create a notification channel.

Only available for Android (SDK 26+).

| Param         | Type      |
| ------------- | --------- |
| **`options`** | `Channel` |

**Since:** 1.4.0

______________________________________________________________________

### deleteChannel(...)

```
deleteChannel(options: DeleteChannelOptions) => Promise<void>
```

Delete a notification channel.

Only available for Android (SDK 26+).

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `DeleteChannelOptions` |

**Since:** 1.4.0

______________________________________________________________________

### listChannels()

```
listChannels() => Promise<ListChannelsResult>
```

List the available notification channels.

Only available for Android (SDK 26+).

**Returns:** `Promise<ListChannelsResult>`

**Since:** 1.4.0

______________________________________________________________________

### addListener('tokenReceived', ...)

```
addListener(eventName: 'tokenReceived', listenerFunc: TokenReceivedListener) => Promise<PluginListenerHandle>
```

Called when a new FCM token is received.

Only available for Android and iOS.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'tokenReceived'`       |
| **`listenerFunc`** | `TokenReceivedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.2

______________________________________________________________________

### addListener('notificationReceived', ...)

```
addListener(eventName: 'notificationReceived', listenerFunc: NotificationReceivedListener) => Promise<PluginListenerHandle>
```

Called when a new push notification is received.

On **Android**, this listener is called for every push notification if the app is in the *foreground*. If the app is in the *background*, then this listener is only called on data push notifications. See https://firebase.google.com/docs/cloud-messaging/android/receive#handling_messages for more information.

On **iOS**, this listener is called for every push notification if the app is in the *foreground*. If the app is in the *background*, then this listener is only called for silent push notifications (messages with the `content-available` key). See https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html for more information.

| Param              | Type                           |
| ------------------ | ------------------------------ |
| **`eventName`**    | `'notificationReceived'`       |
| **`listenerFunc`** | `NotificationReceivedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.2

______________________________________________________________________

### addListener('notificationActionPerformed', ...)

```
addListener(eventName: 'notificationActionPerformed', listenerFunc: NotificationActionPerformedListener) => Promise<PluginListenerHandle>
```

Called when a new push notification action is performed.

Only available for Android and iOS.

| Param              | Type                                  |
| ------------------ | ------------------------------------- |
| **`eventName`**    | `'notificationActionPerformed'`       |
| **`listenerFunc`** | `NotificationActionPerformedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.2.2

______________________________________________________________________

### addListener('apnsTokenReceived', ...)

```
addListener(eventName: 'apnsTokenReceived', listenerFunc: ApnsTokenReceivedListener) => Promise<PluginListenerHandle>
```

Called when the APNs token is received.

Only available for iOS.

| Param              | Type                        |
| ------------------ | --------------------------- |
| **`eventName`**    | `'apnsTokenReceived'`       |
| **`listenerFunc`** | `ApnsTokenReceivedListener` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.2.2

______________________________________________________________________

### Interfaces

#### PermissionStatus

| Prop          | Type              | Since |
| ------------- | ----------------- | ----- |
| **`receive`** | `PermissionState` | 0.2.2 |

#### IsSupportedResult

| Prop              | Type      | Since |
| ----------------- | --------- | ----- |
| **`isSupported`** | `boolean` | 0.3.1 |

#### GetTokenResult

| Prop        | Type     | Since |
| ----------- | -------- | ----- |
| **`token`** | `string` | 0.2.2 |

#### GetTokenOptions

| Prop                            | Type                        | Description                                                                                                                                                                                                |
| ------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`vapidKey`**                  | `string`                    | Your VAPID public key, which is required to retrieve the current registration token on the web. Only available for Web.                                                                                    |
| **`serviceWorkerRegistration`** | `ServiceWorkerRegistration` | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. Only available for Web. |

#### GetDeliveredNotificationsResult

| Prop                | Type             | Since |
| ------------------- | ---------------- | ----- |
| **`notifications`** | `Notification[]` | 0.2.2 |

#### Notification

| Prop              | Type      | Description                                                                                                     | Since |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------- | ----- |
| **`body`**        | `string`  | The notification payload.                                                                                       | 0.2.2 |
| **`clickAction`** | `string`  | The action to be performed on the user opening the notification. Only available for Android.                    | 0.2.2 |
| **`data`**        | `unknown` | Any additional data that was included in the push notification payload.                                         | 0.2.2 |
| **`id`**          | `string`  | The notification identifier.                                                                                    | 0.2.2 |
| **`image`**       | `string`  | The URL of an image that is downloaded on the device and displayed in the notification. Only available for Web. | 0.2.2 |
| **`link`**        | `string`  | Deep link from the notification. Only available for Android.                                                    | 0.2.2 |
| **`subtitle`**    | `string`  | The notification subtitle. Only available for iOS.                                                              | 0.2.2 |
| **`tag`**         | `string`  | The notification string identifier. Only available for Android.                                                 | 0.4.0 |
| **`title`**       | `string`  | The notification title.                                                                                         | 0.2.2 |

#### RemoveDeliveredNotificationsOptions

| Prop                | Type             | Since |
| ------------------- | ---------------- | ----- |
| **`notifications`** | `Notification[]` | 0.4.0 |

#### SubscribeToTopicOptions

| Prop        | Type     | Description                         | Since |
| ----------- | -------- | ----------------------------------- | ----- |
| **`topic`** | `string` | The name of the topic to subscribe. | 0.2.2 |

#### UnsubscribeFromTopicOptions

| Prop        | Type     | Description                                | Since |
| ----------- | -------- | ------------------------------------------ | ----- |
| **`topic`** | `string` | The name of the topic to unsubscribe from. | 0.2.2 |

#### Channel

| Prop              | Type         | Description                                                                                                                                                                                                                                                | Since |
| ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`description`** | `string`     | The description of this channel (presented to the user).                                                                                                                                                                                                   | 1.4.0 |
| **`id`**          | `string`     | The channel identifier.                                                                                                                                                                                                                                    | 1.4.0 |
| **`importance`**  | `Importance` | The level of interruption for notifications posted to this channel.                                                                                                                                                                                        | 1.4.0 |
| **`lightColor`**  | `string`     | The light color for notifications posted to this channel. Only supported if lights are enabled on this channel and the device supports it. Supported color formats are `#RRGGBB` and `#RRGGBBAA`.                                                          | 1.4.0 |
| **`lights`**      | `boolean`    | Whether notifications posted to this channel should display notification lights, on devices that support it.                                                                                                                                               | 1.4.0 |
| **`name`**        | `string`     | The name of this channel (presented to the user).                                                                                                                                                                                                          | 1.4.0 |
| **`sound`**       | `string`     | The sound that should be played for notifications posted to this channel. Notification channels with an importance of at least `3` should have a sound. The file name of a sound file should be specified relative to the android app `res/raw` directory. | 1.4.0 |
| **`vibration`**   | `boolean`    | Whether notifications posted to this channel should vibrate.                                                                                                                                                                                               | 1.4.0 |
| **`visibility`**  | `Visibility` | The visibility of notifications posted to this channel. This setting is for whether notifications posted to this channel appear on the lockscreen or not, and if so, whether they appear in a redacted form.                                               | 1.4.0 |

#### DeleteChannelOptions

| Prop     | Type     | Description             | Since |
| -------- | -------- | ----------------------- | ----- |
| **`id`** | `string` | The channel identifier. | 1.4.0 |

#### ListChannelsResult

| Prop           | Type        |
| -------------- | ----------- |
| **`channels`** | `Channel[]` |

#### PluginListenerHandle

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

#### TokenReceivedEvent

| Prop        | Type     | Since |
| ----------- | -------- | ----- |
| **`token`** | `string` | 0.2.2 |

#### NotificationReceivedEvent

| Prop               | Type           | Since |
| ------------------ | -------------- | ----- |
| **`notification`** | `Notification` | 0.2.2 |

#### NotificationActionPerformedEvent

| Prop               | Type           | Description                                                      | Since |
| ------------------ | -------------- | ---------------------------------------------------------------- | ----- |
| **`actionId`**     | `string`       | The action performed on the notification.                        | 0.2.2 |
| **`inputValue`**   | `string`       | Text entered on the notification action. Only available for iOS. | 0.2.2 |
| **`notification`** | `Notification` | The notification in which the action was performed.              | 0.2.2 |

#### ApnsTokenReceivedEvent

| Prop        | Type     | Description                                               | Since |
| ----------- | -------- | --------------------------------------------------------- | ----- |
| **`token`** | `string` | The native APNs token as an uppercase hex-encoded string. | 8.2.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### CreateChannelOptions

`Channel`

#### TokenReceivedListener

Callback to receive the token received event.

`(event: TokenReceivedEvent): void`

#### NotificationReceivedListener

Callback to receive the notification received event.

`(event: NotificationReceivedEvent): void`

#### NotificationActionPerformedListener

Callback to receive the notification action performed event.

`(event: NotificationActionPerformedEvent): void`

#### ApnsTokenReceivedListener

Callback to receive the APNs token received event.

`(event: ApnsTokenReceivedEvent): void`

### Enums

#### Importance

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`Min`**     | `1`   | 1.4.0 |
| **`Low`**     | `2`   | 1.4.0 |
| **`Default`** | `3`   | 1.4.0 |
| **`High`**    | `4`   | 1.4.0 |
| **`Max`**     | `5`   | 1.4.0 |

#### Visibility

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`Secret`**  | `-1`  | 1.4.0 |
| **`Private`** | `0`   | 1.4.0 |
| **`Public`**  | `1`   | 1.4.0 |

## FAQ

### What is the difference between the Capacitor Firebase Cloud Messaging plugin and the Capacitor Push Notifications plugin?

The [Capacitor Push Notifications](https://capacitorjs.com/docs/apis/push-notifications) plugin supports Android (FCM) and iOS (APNs). The Capacitor Firebase Cloud Messaging plugin, on the other hand, uses the Firebase SDK for [Android](https://firebase.google.com/docs/cloud-messaging/android/client), [iOS](https://firebase.google.com/docs/cloud-messaging/ios/client) and [Web](https://firebase.google.com/docs/cloud-messaging/js/client) and provides additional features such as topic subscriptions and the ability to receive notifications in the foreground.

### Why is the `notificationReceived` listener not called when the app is in the background?

This is the expected behavior of the underlying platforms. On Android, the listener is called for every push notification only while the app is in the foreground. If the app is in the background, it is only called for data push notifications. On iOS, the listener is only called in the background for silent push notifications, which are messages with the `content-available` key.

### Why is my push notification icon on Android displayed as a white square?

Android expects the push notification icon to consist of white pixels on a transparent background. If no dedicated icon is specified, Android falls back to the application icon, which usually does not meet this requirement and is therefore displayed as a white square or circle. Provide a separate push notification icon as described in the [Installation](#installation) section.

### Do I need to request permissions before receiving push notifications?

Yes, use the `checkPermissions()` and `requestPermissions()` methods to check and request the permission to receive push notifications, as shown in the [usage example](#check-and-request-permissions) above. On Android, these methods only need to be called on Android 13+.

## Related Plugins

- [Firebase Authentication](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Sign in users with Firebase Authentication.
- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and user properties with Firebase Analytics.
- [Badge](https://capawesome.io/docs/sdks/capacitor/badge/): Access and update the badge number of the app icon.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/messaging/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/messaging/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Cloud Storage Plugin

Unofficial Capacitor plugin for [Firebase Cloud Storage](https://firebase.google.com/docs/storage/).[1](#fn:1)

## Use Cases

The Firebase Cloud Storage plugin is typically used to store and serve user-generated content, for example:

- **User-generated content**: Upload photos or other files created by your users to Cloud Storage.
- **File downloads**: Download files to the local file system on Android and iOS or as a `Blob` on the Web.
- **Content delivery**: Retrieve the download URL of a file to display or share it.
- **File management**: List the files in a directory, read and update their metadata, or delete them.

## 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     |

## Guides

- [Upload & Manage Files with Firebase Storage in Capacitor](https://capawesome.io/blog/capacitor-firebase-cloud-storage-guide/): Upload, download, and manage user-generated files with this plugin.
- [How to Wrap an Angular App with Capacitor and Firebase](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/): Uses this plugin alongside Cloud Firestore to store and serve user-uploaded files.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): The shared Firebase setup, and how file storage pairs with the database and sign-in.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/storage` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/storage
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://firebase.google.com/docs/android/setup) / [iOS](https://firebase.google.com/docs/ios/setup)).

### Android

#### 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:

- `$firebaseStorageVersion` version of `com.google.firebase:firebase-storage` (default: `22.0.1`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/storage": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to upload and download files, get a download URL, list files, read and update file metadata, delete files, and connect to the Cloud Storage emulator.

### Upload a file

Upload a file to Cloud Storage. On Android and iOS, provide the `uri` to the file to upload. On the Web, provide the data to upload as a `Blob` using the `blob` option instead. The callback is invoked with the upload progress and with `completed` set to `true` once the upload is finished:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const uploadFile = async () => {
  return new Promise((resolve, reject) => {
    FirebaseStorage.uploadFile(
      {
        path: 'images/mountains.png',
        uri: 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/092F8464-DE60-40B3-8A23-EB83160D9F9F/mountains.png',
      },
      (event, error) => {
        if (error) {
          reject(error);
        } else if (event?.completed) {
          resolve();
        }
      }
    );
  });
};
```

### Download a file

Download a file from Cloud Storage. On Android and iOS, the file is downloaded to the local file system using the `uri` option. On the Web, the downloaded file is returned as a `Blob` in the callback event:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const downloadFileWithFirebaseStorage = async () => {
  return new Promise((resolve, reject) => {
    FirebaseStorage.downloadFile(
      {
        path: 'images/mountains.png',
        uri: 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/mountains.png', // Only available for Android and iOS
      },
      (event, error) => {
        if (error) {
          reject(error);
        } else if (event?.completed) {
          // On Web, the downloaded file is available as a Blob in event.blob
          resolve(event?.blob);
        }
      }
    );
  });
};
```

### Download a file with the Filesystem plugin

Alternatively, you can retrieve the download URL of the file and download it using the official [Capacitor Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';
import { Filesystem, Directory } from '@capacitor/filesystem';

const downloadFileWithFilesystem = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  const { path } = await Filesystem.downloadFile({
    url: downloadUrl,
    path: 'mountains.png',
    directory: Directory.Cache,
  });
  return path;
};
```

### Get a download URL

Retrieve the download URL of a file, for example to display or share it:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const getDownloadUrl = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  return downloadUrl;
};
```

### List files in a directory

List the files in a directory. Use the `maxResults` and `pageToken` options to paginate through large directories:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const listFiles = async () => {
  const { items } = await FirebaseStorage.listFiles({
    path: 'images',
  });
  return items;
};
```

### Read and update file metadata

Read the metadata of a file, such as its size, content type, and timestamps, or update it, including user-defined custom metadata:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const getMetadata = async () => {
  const result = await FirebaseStorage.getMetadata({
    path: 'images/mountains.png',
  });
  return result;
};

const updateMetadata = async () => {
  await FirebaseStorage.updateMetadata({
    path: 'images/mountains.png',
    metadata: {
      contentType: 'image/png',
      customMetadata: {
        foo: 'bar',
      },
    },
  });
};
```

### Delete a file

Delete a file from Cloud Storage:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const deleteFile = async () => {
  await FirebaseStorage.deleteFile({
    path: 'images/mountains.png',
  });
};
```

### Use the Cloud Storage emulator

During development, you can instrument your app to talk to the local Cloud Storage emulator. When using an Android emulator device, `10.0.2.2` is the special IP address to connect to the `localhost` of the host computer. Note that on Android, the cleartext traffic must be allowed, which is not intended for use in production:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

const useEmulator = async () => {
  await FirebaseStorage.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};
```

## API

- [`deleteFile(...)`](#deletefile)
- [`getDownloadUrl(...)`](#getdownloadurl)
- [`getMetadata(...)`](#getmetadata)
- [`listFiles(...)`](#listfiles)
- [`updateMetadata(...)`](#updatemetadata)
- [`downloadFile(...)`](#downloadfile)
- [`uploadFile(...)`](#uploadfile)
- [`useEmulator(...)`](#useemulator)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### deleteFile(...)

```
deleteFile(options: DeleteFileOptions) => Promise<void>
```

Delete a file.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `DeleteFileOptions` |

**Since:** 5.3.0

______________________________________________________________________

### getDownloadUrl(...)

```
getDownloadUrl(options: GetDownloadUrlOptions) => Promise<GetDownloadUrlResult>
```

Get the download url for a file.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `GetDownloadUrlOptions` |

**Returns:** `Promise<GetDownloadUrlResult>`

**Since:** 5.3.0

______________________________________________________________________

### getMetadata(...)

```
getMetadata(options: GetMetadataOptions) => Promise<GetMetadataResult>
```

Get the metadata for a file.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `GetMetadataOptions` |

**Returns:** `Promise<GetMetadataResult>`

**Since:** 5.3.0

______________________________________________________________________

### listFiles(...)

```
listFiles(options: ListFilesOptions) => Promise<ListFilesResult>
```

List files in a directory.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `ListFilesOptions` |

**Returns:** `Promise<ListFilesResult>`

**Since:** 5.3.0

______________________________________________________________________

### updateMetadata(...)

```
updateMetadata(options: UpdateMetadataOptions) => Promise<void>
```

Update the metadata for a file.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `UpdateMetadataOptions` |

**Since:** 5.3.0

______________________________________________________________________

### downloadFile(...)

```
downloadFile(options: DownloadFileOptions, callback: DownloadFileCallback) => Promise<CallbackId>
```

Download a file.

On **Android** and **iOS**, the file is downloaded to the local file system using the `uri` option.

On **Web**, the file is downloaded as a `Blob` and returned in the callback event.

| Param          | Type                   |
| -------------- | ---------------------- |
| **`options`**  | `DownloadFileOptions`  |
| **`callback`** | `DownloadFileCallback` |

**Returns:** `Promise<string>`

**Since:** 8.2.0

______________________________________________________________________

### uploadFile(...)

```
uploadFile(options: UploadFileOptions, callback: UploadFileCallback) => Promise<CallbackId>
```

Upload a file.

| Param          | Type                 |
| -------------- | -------------------- |
| **`options`**  | `UploadFileOptions`  |
| **`callback`** | `UploadFileCallback` |

**Returns:** `Promise<string>`

**Since:** 5.3.0

______________________________________________________________________

### useEmulator(...)

```
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

Instrument your app to talk to the Cloud Storage emulator.

On Android, the cleartext traffic must be allowed. On the Capacitor configuration:

```
{
  server: {
    cleartext: true
  }
}
```

**The cleartext traffic is not intended for use in production.**

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `UseEmulatorOptions` |

**Since:** 6.1.0

______________________________________________________________________

### Interfaces

#### DeleteFileOptions

| Prop       | Type     | Description                                                   | Since |
| ---------- | -------- | ------------------------------------------------------------- | ----- |
| **`path`** | `string` | The full path to the file to delete, including the file name. | 5.3.0 |

#### GetDownloadUrlResult

| Prop              | Type     | Description                    | Since |
| ----------------- | -------- | ------------------------------ | ----- |
| **`downloadUrl`** | `string` | The download url for the file. | 5.3.0 |

#### GetDownloadUrlOptions

| Prop       | Type     | Description                                                                     | Since |
| ---------- | -------- | ------------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The full path to the file to get the download url for, including the file name. | 5.3.0 |

#### GetMetadataResult

| Prop                     | Type                         | Description                                                                       | Since |
| ------------------------ | ---------------------------- | --------------------------------------------------------------------------------- | ----- |
| **`bucket`**             | `string`                     | The bucket this file is contained in.                                             | 5.3.0 |
| **`createdAt`**          | `number`                     | The timestamp at which the file was created in milliseconds since the epoch.      | 5.3.0 |
| **`generation`**         | `string`                     | The object's generation.                                                          | 5.3.0 |
| **`md5Hash`**            | `string`                     | The md5 hash of the file.                                                         | 5.3.0 |
| **`metadataGeneration`** | `string`                     | The object's metadata generation.                                                 | 5.3.0 |
| **`name`**               | `string`                     | The short name of this file, which is the last component of the full path.        | 5.3.0 |
| **`path`**               | `string`                     | The full path to the file, including the file name.                               | 5.3.0 |
| **`size`**               | `number`                     | The size of the file in bytes.                                                    | 5.3.0 |
| **`updatedAt`**          | `number`                     | The timestamp at which the file was last updated in milliseconds since the epoch. | 5.3.0 |
| **`cacheControl`**       | `string`                     | Served as the `Cache-Control` header on object download.                          | 6.1.0 |
| **`contentDisposition`** | `string`                     | Served as the `Content-Disposition` header on object download.                    | 6.1.0 |
| **`contentEncoding`**    | `string`                     | Served as the `Content-Encoding` header on object download.                       | 6.1.0 |
| **`contentLanguage`**    | `string`                     | Served as the `Content-Language` header on object download.                       | 6.1.0 |
| **`contentType`**        | `string`                     | Served as the `Content-Type` header on object download.                           | 6.1.0 |
| **`customMetadata`**     | `{ [key: string]: string; }` | Additional user-defined custom metadata.                                          | 6.1.0 |

#### GetMetadataOptions

| Prop       | Type     | Description                                                                 | Since |
| ---------- | -------- | --------------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The full path to the file to get the metadata for, including the file name. | 5.3.0 |

#### ListFilesResult

| Prop                | Type                 | Description                                                                           | Since |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------- | ----- |
| **`items`**         | `StorageReference[]` | The list of files in the directory.                                                   | 5.3.0 |
| **`nextPageToken`** | `string`             | If set, there might be more results for this list. Use this token to resume the list. | 5.3.0 |

#### StorageReference

| Prop         | Type     | Description                                                                | Since |
| ------------ | -------- | -------------------------------------------------------------------------- | ----- |
| **`bucket`** | `string` | The bucket this file is contained in.                                      | 5.3.0 |
| **`path`**   | `string` | The full path to the file, including the file name.                        | 5.3.0 |
| **`name`**   | `string` | The short name of this file, which is the last component of the full path. | 5.3.0 |

#### ListFilesOptions

| Prop             | Type     | Description                                                                                                             | Default | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`path`**       | `string` | The full path to the directory to list files for.                                                                       |         | 5.3.0 |
| **`maxResults`** | `number` | The maximum number of results to return.                                                                                | `1000`  | 5.3.0 |
| **`pageToken`**  | `string` | The page token, returned by a previous call to this method. If provided, listing is resumed from the previous position. |         | 5.3.0 |

#### UpdateMetadataOptions

| Prop           | Type               | Description                                                                    | Since |
| -------------- | ------------------ | ------------------------------------------------------------------------------ | ----- |
| **`path`**     | `string`           | The full path to the file to update the metadata for, including the file name. | 5.3.0 |
| **`metadata`** | `SettableMetadata` | The metadata to update.                                                        | 5.3.0 |

#### SettableMetadata

| Prop                     | Type                         | Description                                                    | Since |
| ------------------------ | ---------------------------- | -------------------------------------------------------------- | ----- |
| **`cacheControl`**       | `string`                     | Served as the `Cache-Control` header on object download.       | 5.3.0 |
| **`contentDisposition`** | `string`                     | Served as the `Content-Disposition` header on object download. | 5.3.0 |
| **`contentEncoding`**    | `string`                     | Served as the `Content-Encoding` header on object download.    | 5.3.0 |
| **`contentLanguage`**    | `string`                     | Served as the `Content-Language` header on object download.    | 5.3.0 |
| **`contentType`**        | `string`                     | Served as the `Content-Type` header on object download.        | 5.3.0 |
| **`customMetadata`**     | `{ [key: string]: string; }` | Additional user-defined custom metadata.                       | 5.3.0 |

#### DownloadFileOptions

| Prop       | Type     | Description                                                          | Since |
| ---------- | -------- | -------------------------------------------------------------------- | ----- |
| **`path`** | `string` | The full path to the file to download, including the file name.      | 8.2.0 |
| **`uri`**  | `string` | The uri to download the file to. Only available for Android and iOS. | 8.2.0 |

#### DownloadFileCallbackEvent

| Prop                   | Type      | Description                                                                         | Since |
| ---------------------- | --------- | ----------------------------------------------------------------------------------- | ----- |
| **`progress`**         | `number`  | The download progress, as a percentage between 0 and 1.                             | 8.2.0 |
| **`bytesTransferred`** | `number`  | The number of bytes that have been transferred. Only available for Android and Web. | 8.2.0 |
| **`totalBytes`**       | `number`  | The total number of bytes to be transferred. Only available for Android and Web.    | 8.2.0 |
| **`completed`**        | `boolean` | Whether the download is completed or not.                                           | 8.2.0 |
| **`blob`**             | `Blob`    | The downloaded file as a Blob. Only available for Web.                              | 8.2.0 |

#### UploadFileOptions

| Prop           | Type             | Description                                                           | Since |
| -------------- | ---------------- | --------------------------------------------------------------------- | ----- |
| **`blob`**     | `Blob`           | The data to upload. Only available for Web.                           | 5.3.0 |
| **`path`**     | `string`         | The full path where data should be uploaded, including the file name. | 5.3.0 |
| **`uri`**      | `string`         | The uri to the file to upload. Only available for Android and iOS.    | 5.3.0 |
| **`metadata`** | `UploadMetadata` | The metadata to set for the file.                                     | 5.4.0 |

#### UploadMetadata

| Prop          | Type     | Description                                                      | Since |
| ------------- | -------- | ---------------------------------------------------------------- | ----- |
| **`md5Hash`** | `string` | The base64-encoded MD5 hash of the file. Only available for Web. | 5.4.0 |

#### UploadFileCallbackEvent

| Prop                   | Type      | Description                                                                         | Since |
| ---------------------- | --------- | ----------------------------------------------------------------------------------- | ----- |
| **`progress`**         | `number`  | The upload progress, as a percentage between 0 and 1.                               | 5.3.0 |
| **`bytesTransferred`** | `number`  | The number of bytes that have been transferred. Only available for Android and Web. | 5.3.0 |
| **`totalBytes`**       | `number`  | The total number of bytes to be transferred. Only available for Android and Web.    | 5.3.0 |
| **`completed`**        | `boolean` | Whether the upload is completed or not.                                             | 5.3.0 |

#### UseEmulatorOptions

| Prop       | Type     | Description                                                                                                                                                                     | Default | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`host`** | `string` | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. |         | 6.1.0 |
| **`port`** | `number` | The emulator port.                                                                                                                                                              | `9199`  | 6.1.0 |

### Type Aliases

#### DownloadFileCallback

`(event: DownloadFileCallbackEvent | null, error: any): void`

#### CallbackId

`string`

#### UploadFileCallback

`(event: UploadFileCallbackEvent | null, error: any): void`

## FAQ

### How do I track the progress of an upload or download?

The `uploadFile(...)` and `downloadFile(...)` methods accept a callback that is invoked with events containing the `progress` as a fraction between 0 and 1 and a `completed` flag. The `bytesTransferred` and `totalBytes` properties are only available on Android and Web.

### How does downloading a file differ between the platforms?

On Android and iOS, the file is downloaded to the local file system using the `uri` option. On the Web, the downloaded file is returned as a `Blob` in the callback event. Alternatively, you can retrieve the download URL with `getDownloadUrl(...)` and download the file with the official Capacitor Filesystem plugin, as shown in the [usage example](#download-a-file-with-the-filesystem-plugin) above.

### How do I upload a file selected by the user?

On Android and iOS, pass the `uri` of the file to the `uploadFile(...)` method. On the Web, pass the data as a `Blob` using the `blob` option instead. You can use the [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/) plugin to let the user select a file on the device.

### How can I store additional information about a file?

You can set metadata for a file when uploading it using the `metadata` option or update it later with `updateMetadata(...)`, including user-defined key-value pairs via `customMetadata`. Use `getMetadata(...)` to read the metadata of a file, such as its size, content type, and timestamps.

### Can I test against the Cloud Storage emulator?

Yes, use the `useEmulator(...)` method to instrument your app to talk to the local Cloud Storage emulator, as shown in the [usage example](#use-the-cloud-storage-emulator) above. When testing on an Android emulator device, use `10.0.2.2` as the host to reach the `localhost` of the host computer. Keep in mind that on Android, the cleartext traffic must be allowed for this, which is not intended for use in production.

## Related Plugins

- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select a file, directory, image, or video from the device.
- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress files such as PNG, JPEG, and WebP images before uploading them.
- [Firebase Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/): Store and sync app data in Cloud Firestore.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/storage/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/storage/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Crashlytics Plugin

Unofficial Capacitor plugin for [Firebase Crashlytics](https://firebase.google.com/docs/crashlytics/).[1](#fn:1)

## Use Cases

The Firebase Crashlytics plugin is typically used to monitor the stability of an app in production, for example:

- **Crash reporting**: Collect crash reports from your app on Android and iOS and inspect them in the Firebase Console.
- **Non-fatal error tracking**: Record handled exceptions with `recordException(...)`, including JavaScript stack traces generated by stacktrace.js.
- **Debugging context**: Attach custom keys, log messages, and a user ID to your reports to make crashes easier to reproduce.
- **Privacy compliance**: Enable or disable automatic data collection at runtime, for example after the user has given their consent.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [Crash Reporting in a Capacitor App with Crashlytics](https://capawesome.io/blog/capacitor-firebase-crashlytics-guide/): Crash and non-fatal error reporting with custom keys, logs, and user IDs using this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): Where crash reporting fits in a production Firebase app, next to analytics and performance.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/crashlytics` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/crashlytics
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios)).

### Android

#### Crashlytics Gradle plugin

First, add the dependency for the Crashlytics Gradle plugin to your root-level (project-level) Gradle file (`<project>/build.gradle`):

```
buildscript {
    dependencies {
+       // Add the dependency for the Crashlytics Gradle plugin
+       classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.9'
    }
}
```

Add the Crashlytics Gradle plugin to your module (app-level) Gradle file (usually `<project>/<app-module>/build.gradle`):

```
apply plugin: 'com.google.firebase.crashlytics'
```

#### 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:

- `$firebaseCrashlyticsVersion` version of `com.google.firebase:firebase-crashlytics` (default: `20.0.3`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/crashlytics": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

#### dSYM Upload

To generate human readable crash reports, Crashlytics needs your project's debug symbol (dSYM) files. The following steps describe how to automatically upload dSYM files to Firebase whenever you build your app:

1. Open your project's Xcode workspace, then select its project file in the left navigator.

1. From the **TARGETS** list, select your main build target.

1. Click the **Build Settings** tab, then complete the following steps so that Xcode produces dSYMs for your builds.

1. Click **All**, then search for `debug information format`.

1. Set **Debug Information Format** to `DWARF with dSYM File` for all your build types.

1. Click the **Build Phases** tab and complete the following steps:

1. Click the **+** button, then select **New Run Script Phase**.

   Make sure this new **Run Script** phase is your project's last build phase; otherwise, Crashlytics can't properly process dSYMs. 2. Expand the new **Run Script** section. 3. In the script field (located under the *Shell* label), add the run script based on your package manager:

   **CocoaPods:**

   ```
   "${PODS_ROOT}/FirebaseCrashlytics/run"
   ```

   **Swift Package Manager:**

   ```
   "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"
   ```

1. In the **Input Files** section, add the paths for the locations of the following files based on your package manager:

   **CocoaPods:**

   ```
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
   ```

   ```
   $(SRCROOT)/$(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)
   ```

   **Swift Package Manager:**

   ```
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
   ```

   ```
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}
   ```

   ```
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist
   ```

   ```
   $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist
   ```

   ```
   $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)
   ```

   If you have `ENABLE_USER_SCRIPT_SANDBOXING=YES` and `ENABLE_DEBUG_DYLIB=YES` in your project build settings, also include:

   ```
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}.debug.dylib
   ```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to force a test crash, record non-fatal exceptions, add context to crash reports, manage automatic data collection, and handle unsent reports. All methods are only available on Android and iOS.

### Force a test crash

Force a crash to test your Crashlytics implementation:

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const crash = async () => {
  await FirebaseCrashlytics.crash({ message: 'Test' });
};
```

### Record a non-fatal exception

Record a handled error as a non-fatal report. You can also attach a JavaScript stack trace generated by [stacktrace.js](https://www.stacktracejs.com/):

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';
import * as StackTrace from 'stacktrace-js';

const recordException = async () => {
  await FirebaseCrashlytics.recordException({
    message: 'This is a non-fatal message.',
  });
};

const recordExceptionWithStacktrace = async (error: Error) => {
  const stacktrace = await StackTrace.fromError(error);
  await FirebaseCrashlytics.recordException({
    message: 'This is a non-fatal message.',
    stacktrace,
  });
};
```

### Add context to your crash reports

Set custom keys, a user ID, or log messages that are associated with subsequent fatal and non-fatal reports. This gives you more context for the events leading up to a crash:

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const setCustomKey = async () => {
  await FirebaseCrashlytics.setCustomKey({
    key: 'page',
    value: 'home',
    type: 'string',
  });
};

const setUserId = async () => {
  await FirebaseCrashlytics.setUserId({
    userId: '123',
  });
};

const log = async () => {
  await FirebaseCrashlytics.log({
    message: 'Test',
  });
};
```

### Enable or disable automatic data collection

Control whether Crashlytics collects data automatically. The value does not apply until the next run of the app. Checking the current setting with `isEnabled()` is only available on iOS:

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const setEnabled = async () => {
  await FirebaseCrashlytics.setEnabled({
    enabled: true,
  });
};

const isEnabled = async () => {
  const { enabled } = await FirebaseCrashlytics.isEnabled();
  return enabled;
};
```

### Check if the app crashed on the previous execution

Find out whether the app crashed during its previous run, for example to show the user a feedback dialog:

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const didCrashOnPreviousExecution = async () => {
  const { crashed } = await FirebaseCrashlytics.didCrashOnPreviousExecution();
  return crashed;
};
```

### Manage unsent crash reports

If automatic data collection is disabled, you can decide whether unsent reports should be uploaded at the next startup or deleted from the device:

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const sendUnsentReports = async () => {
  await FirebaseCrashlytics.sendUnsentReports();
};

const deleteUnsentReports = async () => {
  await FirebaseCrashlytics.deleteUnsentReports();
};
```

## API

- [`crash(...)`](#crash)
- [`setCustomKey(...)`](#setcustomkey)
- [`setUserId(...)`](#setuserid)
- [`log(...)`](#log)
- [`setEnabled(...)`](#setenabled)
- [`isEnabled()`](#isenabled)
- [`didCrashOnPreviousExecution()`](#didcrashonpreviousexecution)
- [`sendUnsentReports()`](#sendunsentreports)
- [`deleteUnsentReports()`](#deleteunsentreports)
- [`recordException(...)`](#recordexception)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### crash(...)

```
crash(options: CrashOptions) => Promise<void>
```

Forces a crash to test the implementation.

Only available for Android and iOS.

| Param         | Type           |
| ------------- | -------------- |
| **`options`** | `CrashOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setCustomKey(...)

```
setCustomKey(options: SetCustomKeyOptions) => Promise<void>
```

Sets a custom key and value that is associated with subsequent fatal and non-fatal reports.

Only available for Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `CustomKeyAndValue` |

**Since:** 0.1.0

______________________________________________________________________

### setUserId(...)

```
setUserId(options: SetUserIdOptions) => Promise<void>
```

Sets a user ID (identifier) that is associated with subsequent fatal and non-fatal reports.

Only available for Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetUserIdOptions` |

**Since:** 0.1.0

______________________________________________________________________

### log(...)

```
log(options: LogOptions) => Promise<void>
```

Adds a custom log message that is sent with your crash data to give yourself more context for the events leading up to a crash.

Only available for Android and iOS.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `LogOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setEnabled(...)

```
setEnabled(options: SetEnabledOptions) => Promise<void>
```

Enables/disables automatic data collection. The value does not apply until the next run of the app.

Only available for Android and iOS.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetEnabledOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Returns whether or not automatic data collection is enabled.

Only available for iOS.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### didCrashOnPreviousExecution()

```
didCrashOnPreviousExecution() => Promise<DidCrashOnPreviousExecutionResult>
```

Returns whether the app crashed during the previous execution.

Only available for Android and iOS.

**Returns:** `Promise<DidCrashOnPreviousExecutionResult>`

**Since:** 0.1.0

______________________________________________________________________

### sendUnsentReports()

```
sendUnsentReports() => Promise<void>
```

Uploads any unsent reports to Crashlytics at next startup.

When automatic data collection is enabled, Crashlytics automatically uploads reports at startup.

Only available for Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### deleteUnsentReports()

```
deleteUnsentReports() => Promise<void>
```

Deletes any unsent reports on the device.

Only available for Android and iOS.

**Since:** 0.1.0

______________________________________________________________________

### recordException(...)

```
recordException(options: RecordExceptionOptions) => Promise<void>
```

Records a non-fatal report to send to Crashlytics.

Only available for Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `RecordExceptionOptions` |

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### CrashOptions

| Prop          | Type     | Since |
| ------------- | -------- | ----- |
| **`message`** | `string` | 0.1.0 |

#### CustomKeyAndValue

| Prop        | Type       | Since     |
| ----------- | ---------- | --------- |
| **`key`**   | `string`   | 7.1.0     |
| **`value`** | \`string   | number    |
| **`type`**  | \`'string' | 'boolean' |

#### SetUserIdOptions

| Prop         | Type     | Since |
| ------------ | -------- | ----- |
| **`userId`** | `string` | 0.1.0 |

#### LogOptions

| Prop          | Type     | Since |
| ------------- | -------- | ----- |
| **`message`** | `string` | 0.1.0 |

#### SetEnabledOptions

| Prop          | Type      | Since |
| ------------- | --------- | ----- |
| **`enabled`** | `boolean` | 0.1.0 |

#### IsEnabledResult

| Prop          | Type      | Since |
| ------------- | --------- | ----- |
| **`enabled`** | `boolean` | 0.1.0 |

#### DidCrashOnPreviousExecutionResult

| Prop          | Type      | Since |
| ------------- | --------- | ----- |
| **`crashed`** | `boolean` | 0.1.0 |

#### RecordExceptionOptions

| Prop                | Type                  | Description                                                                                                                                                                                    | Since |
| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`message`**       | `string`              | The message to record as a non-fatal exception.                                                                                                                                                | 0.1.0 |
| **`code`**          | `number`              | Error code within a specific error domain. **Attention:** This option is ignored on iOS if `stacktrace` is provided. Only available for iOS.                                                   | 0.1.0 |
| **`domain`**        | `string`              | A string containing the error domain. **Attention:** This option is ignored on iOS if `stacktrace` is provided. Only available for iOS.                                                        | 0.1.0 |
| **`keysAndValues`** | `CustomKeyAndValue[]` | An array of keys and the values to associate with the non fatal exception, in addition to the app level custom keys. **Attention:** This option is ignored on iOS if `stacktrace` is provided. | 7.1.0 |
| **`stacktrace`**    | `StackFrame[]`        | A stacktrace generated by stacktrace.js.                                                                                                                                                       | 1.1.0 |

#### StackFrame

Subset of the Stacktrace generated by stacktrace.js.

| Prop               | Type     |
| ------------------ | -------- |
| **`lineNumber`**   | `number` |
| **`fileName`**     | `string` |
| **`functionName`** | `string` |

### Type Aliases

#### SetCustomKeyOptions

`CustomKeyAndValue`

## Test your implementation

[Here](https://firebase.google.com/docs/crashlytics/force-a-crash) you can find more information on how to test the Firebase Crashlytics implementation. Among other things, you will find information on how to correctly [adjust the project's debug settings](https://firebase.google.com/docs/crashlytics/force-a-crash?platform=ios#adjust_your_projects_debug_settings) under iOS and how to [test it out](https://firebase.google.com/docs/crashlytics/force-a-crash?platform=ios#test_it_out).

If you get obfuscated crash reports for iOS, make sure you have [initialized Crashlytics](https://firebase.google.com/docs/crashlytics/get-started?platform=ios#initialize-crashlytics) correctly and take a look at [this guide](https://firebase.google.com/docs/crashlytics/get-deobfuscated-reports?platform=ios), which provides some ways to troubleshoot if Crashlytics can't find your app's dSYM.

## FAQ

### Does this plugin work on the Web?

No, the plugin methods are only available on Android and iOS. Firebase Crashlytics itself does not provide a Web SDK, so crash reporting is limited to the native platforms.

### How can I test my Crashlytics implementation?

Call the `crash(...)` method to force a test crash and verify that it shows up in the Firebase Console. Note that the report is usually sent on the next app start. More information on testing, including how to adjust your project's debug settings on iOS, can be found in the [Test your implementation](#test-your-implementation) section.

### How do I report handled JavaScript errors?

Use the `recordException(...)` method to record a non-fatal report. You can pass a stack trace generated by stacktrace.js via the `stacktrace` option to get readable JavaScript stack traces in the Firebase Console. Be aware that on iOS the `code`, `domain` and `keysAndValues` options are ignored if a `stacktrace` is provided.

### Why are my iOS crash reports not human readable?

Crashlytics needs your project's debug symbol (dSYM) files to generate human readable crash reports on iOS. Follow the steps in the [dSYM Upload](#dsym-upload) section to automatically upload dSYM files to Firebase whenever you build your app.

### Can I disable crash reporting until the user gives consent?

Yes, use the `setEnabled(...)` method to enable or disable automatic data collection at runtime. Note that the value does not apply until the next run of the app. You can then use `sendUnsentReports()` or `deleteUnsentReports()` to decide what happens with reports that have not been uploaded yet.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Unofficial Capacitor plugin for Firebase Analytics.
- [Firebase Performance Monitoring](https://capawesome.io/docs/sdks/capacitor/firebase/performance-monitoring/): Unofficial Capacitor plugin for Firebase Performance Monitoring.
- [Firebase Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/): Unofficial Capacitor plugin for Firebase Remote Config.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/crashlytics/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/crashlytics/LICENSE).

## Credits

This plugin is based on the [Capacitor Community Firebase Crashlytics](https://github.com/capacitor-community/firebase-crashlytics) plugin. Thanks to everyone who contributed to the project!

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Performance Monitoring Plugin

Unofficial Capacitor plugin for [Firebase Performance Monitoring](https://firebase.google.com/docs/perf-mon).[1](#fn:1)

## Use Cases

The Firebase Performance Monitoring plugin is typically used to gain insight into the performance characteristics of your app, for example:

- **Custom code traces**: Measure how long specific tasks in your app take, such as loading data or processing an image.
- **Custom metrics**: Count performance-related events within a trace, such as cache hits or retries.
- **Performance segmentation**: Add custom attributes to your traces, such as a user id, to segment your performance data.
- **Privacy compliance**: Enable or disable performance monitoring at runtime, for example based on the user's consent.

## 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     |
| 1.x.x          | 4.x.x             | Deprecated     |

## Guides

- [Monitor App Performance in Capacitor with Firebase](https://capawesome.io/blog/capacitor-firebase-performance-monitoring-guide/): Automatic and custom traces for app start, rendering, and network calls with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): The whole plugin family in one guide, with performance monitoring as one half of app health.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/performance` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/performance firebase
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

See [Add the Performance Monitoring plugin to your app](https://firebase.google.com/docs/perf-mon/get-started-android#add-perfmon-plugin) 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:

- `$firebasePerfVersion` version of `com.google.firebase:firebase-perf` (default: `22.0.4`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/performance": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Usage

The following examples show how to start and stop traces, record custom metrics, add custom attributes, toggle performance monitoring, and record a trace manually.

### Start and stop a trace

Start a custom code trace to measure how long a specific task in your app takes and stop it as soon as the task is completed:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const startTrace = async () => {
  await FirebasePerformance.startTrace({ traceName: 'test_trace' });
};

const stopTrace = async () => {
  await FirebasePerformance.stopTrace({ traceName: 'test_trace' });
};
```

### Record custom metrics

Set the value of a custom metric for a trace, increment it atomically, or read its current value. Note that metric values are floored down to the nearest integer:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const putMetric = async () => {
  await FirebasePerformance.putMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
    num: 1,
  });
};

const incrementMetric = async () => {
  await FirebasePerformance.incrementMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
    incrementBy: 1,
  });
};

const getMetric = async () => {
  const result = await FirebasePerformance.getMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
  });
  return result.value;
};
```

### Add custom attributes to a trace

Set custom attributes on a trace, for example a user id, to segment your performance data. You can also read or remove them again:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const putAttribute = async () => {
  await FirebasePerformance.putAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
    value: '123',
  });
};

const getAttribute = async () => {
  const result = await FirebasePerformance.getAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
  return result.attributes;
};

const getAttributes = async () => {
  const result = await FirebasePerformance.getAttributes({ traceName: 'test_trace' });
  return result.attributes;
};

const removeAttribute = async () => {
  await FirebasePerformance.removeAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
};
```

### Enable or disable performance monitoring

Enable or disable performance monitoring at runtime, for example based on the user's consent. The setting is applied with the next start of the app:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const setEnabled = async () => {
  await FirebasePerformance.setEnabled({ enabled: true });
};

const isEnabled = async () => {
  const result = await FirebasePerformance.isEnabled();
  return result.enabled;
};
```

### Record a trace manually

Record a trace for a task that has already been completed by providing its start time and duration. Only available on Web:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const record = async () => {
  await FirebasePerformance.record({
    traceName: 'test_trace',
    startTime: Date.now(),
    duration: 1000,
    options: {
      metrics: {
        item_cache_hit: 1,
      },
      attributes: {
        user_id: '123',
      },
    },
  });
};
```

## API

- [`startTrace(...)`](#starttrace)
- [`stopTrace(...)`](#stoptrace)
- [`incrementMetric(...)`](#incrementmetric)
- [`setEnabled(...)`](#setenabled)
- [`isEnabled()`](#isenabled)
- [`putAttribute(...)`](#putattribute)
- [`getAttribute(...)`](#getattribute)
- [`getAttributes(...)`](#getattributes)
- [`removeAttribute(...)`](#removeattribute)
- [`putMetric(...)`](#putmetric)
- [`getMetric(...)`](#getmetric)
- [`record(...)`](#record)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### startTrace(...)

```
startTrace(options: StartTraceOptions) => Promise<void>
```

Starts a trace.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `StartTraceOptions` |

**Since:** 0.1.0

______________________________________________________________________

### stopTrace(...)

```
stopTrace(options: StopTraceOptions) => Promise<void>
```

Stops a trace.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `StopTraceOptions` |

**Since:** 0.1.0

______________________________________________________________________

### incrementMetric(...)

```
incrementMetric(options: IncrementMetricOptions) => Promise<void>
```

Atomically increments the metric with the given name for the selected trace by the `incrementBy` value.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `IncrementMetricOptions` |

**Since:** 0.1.0

______________________________________________________________________

### setEnabled(...)

```
setEnabled(options: SetEnabledOptions) => Promise<void>
```

Enables or disables performance monitoring. Will be applied with the next start of the app.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetEnabledOptions` |

**Since:** 0.1.0

______________________________________________________________________

### isEnabled()

```
isEnabled() => Promise<IsEnabledResult>
```

Determines whether performance monitoring is enabled or disabled.

**Returns:** `Promise<IsEnabledResult>`

**Since:** 0.1.0

______________________________________________________________________

### putAttribute(...)

```
putAttribute(options: PutAttributeOptions) => Promise<void>
```

Sets a custom attribute of a trace to a given value.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `PutAttributeOptions` |

**Since:** 6.3.0

______________________________________________________________________

### getAttribute(...)

```
getAttribute(options: GetAttributeOptions) => Promise<GetAttributeResult>
```

Returns the value of a custom attribute of a trace.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GetAttributeOptions` |

**Returns:** `Promise<GetAttributeResult>`

**Since:** 6.3.0

______________________________________________________________________

### getAttributes(...)

```
getAttributes(options: GetAttributesOptions) => Promise<GetAttributesResult>
```

Gets the all the custom attributes of a trace with their values.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `GetAttributesOptions` |

**Returns:** `Promise<GetAttributesResult>`

**Since:** 6.3.0

______________________________________________________________________

### removeAttribute(...)

```
removeAttribute(options: RemoveAttributeOptions) => Promise<void>
```

Removes a custom attribute from a trace given its name.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `GetAttributeOptions` |

**Since:** 6.3.0

______________________________________________________________________

### putMetric(...)

```
putMetric(options: PutMetricOptions) => Promise<void>
```

Sets the value of a custom metric.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `PutMetricOptions` |

**Since:** 6.3.0

______________________________________________________________________

### getMetric(...)

```
getMetric(options: GetMetricOptions) => Promise<GetMetricResult>
```

Get the value of a custom metric by name.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `GetMetricOptions` |

**Returns:** `Promise<GetMetricResult>`

**Since:** 6.3.0

______________________________________________________________________

### record(...)

```
record(options: RecordOptions) => Promise<void>
```

Records a trace given its name and options.

Only available on web.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `RecordOptions` |

**Since:** 6.3.0

______________________________________________________________________

### Interfaces

#### StartTraceOptions

| Prop            | Type     | Description                                                                                                                                                                                      | Since |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`traceName`** | `string` | Custom trace name. Names for custom code traces must meet the following requirements: no leading or trailing whitespace, no leading underscore (\_) character, and max length is 100 characters. | 0.1.0 |

#### StopTraceOptions

| Prop            | Type     | Description                                       | Since |
| --------------- | -------- | ------------------------------------------------- | ----- |
| **`traceName`** | `string` | Name of the trace that was set with `startTrace`. | 0.1.0 |

#### IncrementMetricOptions

| Prop              | Type     | Description                                       | Default | Since |
| ----------------- | -------- | ------------------------------------------------- | ------- | ----- |
| **`traceName`**   | `string` | Name of the trace that was set with `startTrace`. |         | 0.1.0 |
| **`metricName`**  | `string` | Name of the metric to be incremented.             |         | 0.1.0 |
| **`incrementBy`** | `number` | Amount by which the metric has to be incremented. | `1`     | 0.1.0 |

#### SetEnabledOptions

| Prop          | Type      | Description                               | Since |
| ------------- | --------- | ----------------------------------------- | ----- |
| **`enabled`** | `boolean` | Should performance monitoring be enabled. | 0.1.0 |

#### IsEnabledResult

| Prop          | Type      | Description                                                     | Since |
| ------------- | --------- | --------------------------------------------------------------- | ----- |
| **`enabled`** | `boolean` | `true` if performance monitoring is enabled, otherwise `false`. | 0.1.0 |

#### PutAttributeOptions

| Prop            | Type     | Description                             | Since |
| --------------- | -------- | --------------------------------------- | ----- |
| **`traceName`** | `string` | Name of the trace to set its attribute. | 6.3.0 |
| **`attribute`** | `string` | Name of the attribute to set its value. | 6.3.0 |
| **`value`**     | `string` | The value to set to the attribute.      | 6.3.0 |

#### GetAttributeResult

| Prop        | Type     | Description | Since                              |
| ----------- | -------- | ----------- | ---------------------------------- |
| **`value`** | \`string | null\`      | The value of the custom attribute. |

#### GetAttributeOptions

| Prop            | Type     | Description                                  | Since |
| --------------- | -------- | -------------------------------------------- | ----- |
| **`traceName`** | `string` | Name of the trace to set its attribute.      | 6.3.0 |
| **`attribute`** | `string` | Name of the attribute to retrieve its value. | 6.3.0 |

#### GetAttributesResult

| Prop             | Type                         | Description                                                  | Since |
| ---------------- | ---------------------------- | ------------------------------------------------------------ | ----- |
| **`attributes`** | `{ [key: string]: string; }` | A map of all custom attributes of a trace with their values. | 6.3.0 |

#### GetAttributesOptions

| Prop            | Type     | Description                              | Since |
| --------------- | -------- | ---------------------------------------- | ----- |
| **`traceName`** | `string` | Name of the trace to get its attributes. | 6.3.0 |

#### PutMetricOptions

| Prop             | Type     | Description                                                                              | Since |
| ---------------- | -------- | ---------------------------------------------------------------------------------------- | ----- |
| **`traceName`**  | `string` | Name of the trace to set its metric.                                                     | 6.3.0 |
| **`metricName`** | `string` | The metric name.                                                                         | 6.3.0 |
| **`num`**        | `number` | The value to set for the metric. The given value is floored down to the nearest integer. | 6.3.0 |

#### GetMetricResult

| Prop        | Type     | Description                        | Since |
| ----------- | -------- | ---------------------------------- | ----- |
| **`value`** | `number` | The value of the metric if exists. | 6.3.0 |

#### GetMetricOptions

| Prop             | Type     | Description                          | Since |
| ---------------- | -------- | ------------------------------------ | ----- |
| **`traceName`**  | `string` | Name of the trace to get its metric. | 6.3.0 |
| **`metricName`** | `string` | The metric name.                     | 6.3.0 |

#### RecordOptions

| Prop            | Type                                                                                 | Description                                                                   | Since |
| --------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----- |
| **`traceName`** | `string`                                                                             | Name of the trace to record.                                                  | 6.3.0 |
| **`startTime`** | `number`                                                                             | Start time of the trace since epoch in milliseconds.                          | 6.3.0 |
| **`duration`**  | `number`                                                                             | The duration of the trace in milliseconds.                                    | 6.3.0 |
| **`options`**   | `{ metrics?: { [key: string]: number; }; attributes?: { [key: string]: string; }; }` | An optional object that holds optional maps of custom metrics and attributes. | 6.3.0 |

### Type Aliases

#### RemoveAttributeOptions

`GetAttributeOptions`

## FAQ

### How do I measure the duration of a specific task in my app?

Start a custom code trace with `startTrace(...)` before the task begins and stop it with `stopTrace(...)` as soon as the task is completed, as shown in the [usage example](#start-and-stop-a-trace) above. You can enrich the trace with custom metrics and attributes before stopping it.

### What are the requirements for custom trace names?

Names for custom code traces must not contain leading or trailing whitespace, must not start with an underscore (`_`), and may have a maximum length of 100 characters.

### What is the difference between a metric and an attribute?

A metric is a numeric value of a trace, for example a counter for cache hits, which is set with `putMetric(...)` or incremented with `incrementMetric(...)`. Note that metric values are floored down to the nearest integer. An attribute is a string value of a trace, for example a user id, which is set with `putAttribute(...)` and can be used to segment your performance data.

### Can users disable performance monitoring at runtime?

Yes, call `setEnabled(...)` to enable or disable performance monitoring, for example based on the user's consent. The setting is applied with the next start of the app. Use `isEnabled()` to determine whether performance monitoring is currently enabled or disabled.

### Why does the `record` method not work on Android and iOS?

The `record(...)` method is only available on Web. On Android and iOS, use `startTrace(...)` and `stopTrace(...)` to measure the duration of a task instead.

## Related Plugins

- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and user properties with Firebase Analytics.
- [Firebase Crashlytics](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/): Track and analyze app crashes with Firebase Crashlytics.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/performance/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/performance/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor Firebase Remote Config Plugin

Unofficial Capacitor plugin for [Firebase Remote Config](https://firebase.google.com/docs/remote-config).[1](#fn:1)

## Use Cases

The Firebase Remote Config plugin is typically used to change the behavior and appearance of your app without publishing an app update, for example:

- **Feature flags**: Roll out new features gradually by toggling boolean parameters remotely.
- **Promotions**: Activate sales or promotions remotely, for example via an `is_sale` parameter.
- **Maintenance announcements**: Inform users about upcoming maintenance without releasing a new app version.
- **Real-time updates**: React to configuration changes in real time using the config update listener.
- **Default values**: Provide in-app default values so your app behaves predictably before the first fetch.

## 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     |

## Guides

- [Feature Flags in a Capacitor App with Remote Config](https://capawesome.io/blog/capacitor-firebase-remote-config-guide/): Feature flags, staged rollouts, and real-time config updates with this plugin.
- [How to Use Firebase in a Capacitor App](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/): How feature flags plug into the rest of the family, including the Analytics audiences they target.

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/remote-config` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-firebase/remote-config firebase
npx cap sync
```

Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)).

### Android

Google Analytics is required for the [conditional targeting of app instances](https://firebase.google.com/docs/remote-config/parameters#conditions_rules_and_conditional_values) to user properties and audiences. Make sure that you install the [Capacitor Firebase Analytics](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/analytics) plugin in your project.

#### 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:

- `$firebaseConfigVersion` version of `com.google.firebase:firebase-config` (default: `23.0.1`)

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

### iOS

#### Swift Package Manager

Add the following to your `capacitor.config.json` (or `capacitor.config.ts`) to avoid a [SwiftPM package identity collision](https://github.com/capawesome-team/capacitor-firebase/issues/959):

```
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/remote-config": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**Attention**: SPM `packageOptions` support requires Capacitor CLI **8.4.0+**.

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## Starter templates

The following starter templates are available:

- [Ionstarter Angular Firebase](https://ionstarter.dev/)

## Usage

The following examples show how to fetch and activate the configuration, read configuration values, configure the fetch behavior, set custom signals, and listen for configuration updates in real time.

### Fetch and activate the configuration

Fetch the latest configuration from the Remote Config service and activate it to make it available to the getters. Use `fetchAndActivate()` to perform both operations at once. On Android and iOS, you can pass a minimum fetch interval to `fetchConfig(...)`:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const fetchConfig = async () => {
  await FirebaseRemoteConfig.fetchConfig({
    minimumFetchIntervalInSeconds: 1200,
  });
};

const activate = async () => {
  await FirebaseRemoteConfig.activate();
};

const fetchAndActivate = async () => {
  await FirebaseRemoteConfig.fetchAndActivate();
};
```

### Read configuration values

Read the value for a given key as a boolean, number, or string:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const getBoolean = async () => {
  const { value } = await FirebaseRemoteConfig.getBoolean({
    key: 'is_sale',
  });
  return value;
};

const getNumber = async () => {
  const { value } = await FirebaseRemoteConfig.getNumber({
    key: 'upcoming_maintenance',
  });
  return value;
};

const getString = async () => {
  const { value } = await FirebaseRemoteConfig.getString({
    key: 'license_key',
  });
  return value;
};
```

### Configure the fetch behavior

Set the fetch timeout and the minimum fetch interval. During development, it's recommended to set a relatively low minimum fetch interval:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const setSettings = async () => {
  await FirebaseRemoteConfig.setSettings({
    fetchTimeoutInSeconds: 10,
    minimumFetchIntervalInSeconds: 0,
  });
};
```

### Set custom signals

Set custom signals for the app instance that can be used for targeting in Remote Config conditions. Signals with a `null` value will be removed:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const setCustomSignals = async () => {
  await FirebaseRemoteConfig.setCustomSignals({
    customSignals: {
      city: 'Berlin',
      preferred_event_category: 'concerts',
    },
  });
};
```

### Listen for configuration updates in real time

Add a listener for the config update event to be notified as soon as parameter values change. Only available on Android and iOS:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const addConfigUpdateListener = async () => {
  const callbackId = await FirebaseRemoteConfig.addConfigUpdateListener(
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const removeConfigUpdateListener = async (callbackId: string) => {
  await FirebaseRemoteConfig.removeConfigUpdateListener({
    callbackId,
  });
};
```

### Remove all listeners

Remove all listeners that have been added for this plugin:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

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

## API

- [`activate()`](#activate)
- [`fetchAndActivate()`](#fetchandactivate)
- [`fetchConfig(...)`](#fetchconfig)
- [`getBoolean(...)`](#getboolean)
- [`getNumber(...)`](#getnumber)
- [`getString(...)`](#getstring)
- [`getAll()`](#getall)
- [`getInfo()`](#getinfo)
- [`setMinimumFetchInterval(...)`](#setminimumfetchinterval)
- [`setCustomSignals(...)`](#setcustomsignals)
- [`setDefaults(...)`](#setdefaults)
- [`setSettings(...)`](#setsettings)
- [`addConfigUpdateListener(...)`](#addconfigupdatelistener)
- [`removeConfigUpdateListener(...)`](#removeconfigupdatelistener)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### activate()

```
activate() => Promise<void>
```

Make the last fetched configuration available to the getters.

**Since:** 1.3.0

______________________________________________________________________

### fetchAndActivate()

```
fetchAndActivate() => Promise<void>
```

Perform fetch and activate operations.

**Since:** 1.3.0

______________________________________________________________________

### fetchConfig(...)

```
fetchConfig(options?: FetchConfigOptions | undefined) => Promise<void>
```

Fetch and cache configuration from the Remote Config service.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `FetchConfigOptions` |

**Since:** 1.3.0

______________________________________________________________________

### getBoolean(...)

```
getBoolean(options: GetBooleanOptions) => Promise<GetBooleanResult>
```

Get the value for the given key as a boolean.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetBooleanResult>`

**Since:** 1.3.0

______________________________________________________________________

### getNumber(...)

```
getNumber(options: GetNumberOptions) => Promise<GetNumberResult>
```

Get the value for the given key as a number.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetNumberResult>`

**Since:** 1.3.0

______________________________________________________________________

### getString(...)

```
getString(options: GetStringOptions) => Promise<GetStringResult>
```

Get the value for the given key as a string.

| Param         | Type         |
| ------------- | ------------ |
| **`options`** | `GetOptions` |

**Returns:** `Promise<GetStringResult>`

**Since:** 1.3.0

______________________________________________________________________

### getAll()

```
getAll() => Promise<GetAllResult>
```

Get all the values from the Remote Config service.

**Returns:** `Promise<GetAllResult>`

**Since:** 8.3.0

______________________________________________________________________

### getInfo()

```
getInfo() => Promise<GetInfoResult>
```

Get information about the last fetch operation.

**Returns:** `Promise<GetInfoResult>`

**Since:** 7.5.0

______________________________________________________________________

### setMinimumFetchInterval(...)

```
setMinimumFetchInterval(options: SetMinimumFetchIntervalOptions) => Promise<void>
```

Set the minimum fetch interval.

Only available for Web.

| Param         | Type                             |
| ------------- | -------------------------------- |
| **`options`** | `SetMinimumFetchIntervalOptions` |

**Since:** 1.3.0

______________________________________________________________________

### setCustomSignals(...)

```
setCustomSignals(options: SetCustomSignalsOptions) => Promise<void>
```

Set custom signals for the app instance that can be used for targeting in Remote Config conditions.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `SetCustomSignalsOptions` |

**Since:** 8.4.0

______________________________________________________________________

### setDefaults(...)

```
setDefaults(options: SetDefaultsOptions) => Promise<void>
```

Sets config defaults for parameter keys and values in the default namespace config.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetDefaultsOptions` |

**Since:** 8.3.0

______________________________________________________________________

### setSettings(...)

```
setSettings(options: SetSettingsOptions) => Promise<void>
```

Set the remote config settings.

On Android, the settings values are persisted in SharedPreferences.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetSettingsOptions` |

**Since:** 6.2.0

______________________________________________________________________

### addConfigUpdateListener(...)

```
addConfigUpdateListener(callback: AddConfigUpdateListenerOptionsCallback) => Promise<CallbackId>
```

Add a listener for the config update event.

Only available for Android and iOS.

| Param          | Type                                     |
| -------------- | ---------------------------------------- |
| **`callback`** | `AddConfigUpdateListenerOptionsCallback` |

**Returns:** `Promise<string>`

**Since:** 5.4.0

______________________________________________________________________

### removeConfigUpdateListener(...)

```
removeConfigUpdateListener(options: RemoveConfigUpdateListenerOptions) => Promise<void>
```

Remove a listener for the config update event.

Only available for Android and iOS.

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | `RemoveConfigUpdateListenerOptions` |

**Since:** 5.4.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 5.4.0

______________________________________________________________________

### Interfaces

#### FetchConfigOptions

| Prop                                | Type     | Description                                                                                                                                                                                                               | Default | Since |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`minimumFetchIntervalInSeconds`** | `number` | Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval. Only available for Android and iOS. | `43200` | 1.3.0 |

#### GetBooleanResult

| Prop         | Type             | Description                                     | Since |
| ------------ | ---------------- | ----------------------------------------------- | ----- |
| **`value`**  | `boolean`        | The value for the given key as a boolean.       | 1.3.0 |
| **`source`** | `GetValueSource` | Indicates at which source this value came from. | 1.3.0 |

#### GetOptions

| Prop      | Type     | Description                  | Since |
| --------- | -------- | ---------------------------- | ----- |
| **`key`** | `string` | The key of the value to get. | 1.3.0 |

#### GetNumberResult

| Prop         | Type             | Description                                     | Since |
| ------------ | ---------------- | ----------------------------------------------- | ----- |
| **`value`**  | `number`         | The value for the given key as a number.        | 1.3.0 |
| **`source`** | `GetValueSource` | Indicates at which source this value came from. | 1.3.0 |

#### GetStringResult

| Prop         | Type             | Description                                     | Since |
| ------------ | ---------------- | ----------------------------------------------- | ----- |
| **`value`**  | `string`         | The value for the given key as a string.        | 1.3.0 |
| **`source`** | `GetValueSource` | Indicates at which source this value came from. | 1.3.0 |

#### GetAllResult

| Prop         | Type                                | Description              | Since |
| ------------ | ----------------------------------- | ------------------------ | ----- |
| **`values`** | `Record<string, GetAllResultValue>` | The values for all keys. | 8.3.0 |

#### GetAllResultValue

| Prop         | Type             | Description                                     | Since |
| ------------ | ---------------- | ----------------------------------------------- | ----- |
| **`value`**  | `string`         | The value as a string.                          | 8.3.0 |
| **`source`** | `GetValueSource` | Indicates at which source this value came from. | 8.3.0 |

#### GetInfoResult

| Prop                  | Type              | Description                                                                                                                      | Since |
| --------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`lastFetchTime`**   | `number`          | The Unix timestamp in milliseconds of the last successful fetch, or -1 if no fetch has occurred or initialization is incomplete. | 7.5.0 |
| **`lastFetchStatus`** | `LastFetchStatus` | The status of the last fetch attempt.                                                                                            | 7.5.0 |

#### SetMinimumFetchIntervalOptions

| Prop                                | Type     | Description                                                                                                                                                                           | Default | Since |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`minimumFetchIntervalInSeconds`** | `number` | Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval. | `43200` | 1.3.0 |

#### SetCustomSignalsOptions

| Prop                | Type                     | Description | Since   |
| ------------------- | ------------------------ | ----------- | ------- |
| **`customSignals`** | \`Record\<string, string | number      | null>\` |

#### SetDefaultsOptions

| Prop           | Type                     | Description | Since      |
| -------------- | ------------------------ | ----------- | ---------- |
| **`defaults`** | \`Record\<string, string | number      | boolean>\` |

#### SetSettingsOptions

| Prop                                | Type     | Description                                                                                                                                                                           | Default | Since |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`fetchTimeoutInSeconds`**         | `number` | Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server.                                                          | `60`    | 6.2.0 |
| **`minimumFetchIntervalInSeconds`** | `number` | Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval. | `43200` | 6.2.0 |

#### AddConfigUpdateListenerOptionsCallbackEvent

| Prop              | Type       | Description                                                                        | Since |
| ----------------- | ---------- | ---------------------------------------------------------------------------------- | ----- |
| **`updatedKeys`** | `string[]` | Parameter keys whose values have been updated from the currently activated values. | 5.4.0 |

#### RemoveConfigUpdateListenerOptions

| Prop     | Type         | Description                       | Since |
| -------- | ------------ | --------------------------------- | ----- |
| **`id`** | `CallbackId` | The id of the listener to remove. | 5.4.0 |

### Type Aliases

#### GetBooleanOptions

`GetOptions`

#### GetNumberOptions

`GetOptions`

#### GetStringOptions

`GetOptions`

#### AddConfigUpdateListenerOptionsCallback

`(event: AddConfigUpdateListenerOptionsCallbackEvent | null, error: any): void`

#### CallbackId

`string`

### Enums

#### GetValueSource

| Members       | Value | Description                                                                             | Since |
| ------------- | ----- | --------------------------------------------------------------------------------------- | ----- |
| **`Static`**  | `0`   | Indicates that the value returned is the static default value.                          | 1.3.0 |
| **`Default`** | `1`   | Indicates that the value returned was retrieved from the defaults set by the client.    | 1.3.0 |
| **`Remote`**  | `2`   | Indicates that the value returned was retrieved from the Firebase Remote Config Server. | 1.3.0 |

#### LastFetchStatus

| Members          | Value |
| ---------------- | ----- |
| **`NoFetchYet`** | `0`   |
| **`Success`**    | `1`   |
| **`Failure`**    | `2`   |
| **`Throttled`**  | `3`   |

## FAQ

### Why do the getters return default values instead of the remote ones?

Fetched configuration values must be activated before they are available to the getters. Call `fetchConfig(...)` followed by `activate()`, or use `fetchAndActivate()` to perform both operations at once, as shown in the [usage example](#fetch-and-activate-the-configuration) above.

### How often does the plugin fetch new configuration values?

Fetched configuration values are cached. The minimum fetch interval defines the maximum age in seconds of an entry in the config cache before it is considered stale, with a default of 43200 seconds (12 hours). During development, it's recommended to set a relatively low minimum fetch interval using `setSettings(...)` on Android and iOS or `setMinimumFetchInterval(...)` on Web.

### How can I react to configuration changes in real time?

Use `addConfigUpdateListener(...)` to be notified as soon as parameter values change, including the keys whose values have been updated. This method is only available on Android and iOS. You can remove the listener again with `removeConfigUpdateListener(...)` or `removeAllListeners()`.

### Do I need the Firebase Analytics plugin to use Remote Config?

Google Analytics is only required for the conditional targeting of app instances to user properties and audiences. If you want to use conditions, make sure to also install the [Capacitor Firebase Analytics](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/analytics) plugin in your project.

### How can I tell where a configuration value came from?

The getters return a `source` property in addition to the value. It indicates whether the value is the static default value, was retrieved from the defaults set by the client, or was retrieved from the Firebase Remote Config server.

## Related Plugins

- [Firebase Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and user properties with Firebase Analytics.
- [Live Update](https://capawesome.io/docs/sdks/capacitor/live-update/): Update your app remotely in real-time without requiring users to download a new version from the app store.

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/remote-config/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/remote-config/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# ML Kit Plugins

Our Capacitor ML Kit plugins wrap Google's ML Kit SDKs behind a single JavaScript API, bringing on-device machine learning to your Capacitor app on Android and iOS.

These are unofficial, open-source plugins maintained by Capawesome. Open a plugin's page for installation steps, supported platforms, and the full API reference. Fourteen of the plugins, including the GenAI plugins powered by Gemini Nano, were introduced in version 8.2.0 — read the [Capacitor ML Kit 8.2.0 release announcement](https://capawesome.io/blog/capacitor-mlkit-8-2-0-release/index.md) for an overview.

## Plugins

- [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) — Scan barcodes and QR codes.
- [Digital Ink Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/digital-ink-recognition/index.md) — Recognize handwritten text and hand-drawn shapes.
- [Document Scanner](https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner/index.md) — Scan documents with the device camera.
- [Entity Extraction](https://capawesome.io/docs/sdks/capacitor/mlkit/entity-extraction/index.md) — Detect entities like addresses and dates in text.
- [Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/index.md) — Detect faces in images.
- [Face Mesh Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/index.md) — Detect faces and their mesh in images.
- [GenAI Image Description](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-image-description/index.md) — Describe images with Gemini Nano.
- [GenAI Prompt](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-prompt/index.md) — Send custom prompts to Gemini Nano.
- [GenAI Proofreading](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-proofreading/index.md) — Fix grammar and spelling with Gemini Nano.
- [GenAI Rewriting](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-rewriting/index.md) — Reword text in different tones with Gemini Nano.
- [GenAI Speech Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-speech-recognition/index.md) — Transcribe speech to text with Gemini Nano.
- [GenAI Summarization](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-summarization/index.md) — Summarize text with Gemini Nano.
- [Image Labeling](https://capawesome.io/docs/sdks/capacitor/mlkit/image-labeling/index.md) — Detect and label the content of images.
- [Language Identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/index.md) — Identify the language of a text.
- [Object Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/object-detection/index.md) — Detect and track objects in images.
- [Pose Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/pose-detection/index.md) — Track the position of a person's body.
- [Selfie Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/selfie-segmentation/index.md) — Separate the foreground from the background in selfies.
- [Smart Reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/index.md) — Generate contextual reply suggestions.
- [Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/index.md) — Segment subjects from images.
- [Text Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/text-recognition/index.md) — Extract text from images.
- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/index.md) — Translate text between languages on-device.

## FAQ

### What are the Capacitor ML Kit plugins?

They are packages that expose Google's native ML Kit SDKs through a unified JavaScript API, letting you run on-device machine learning in a Capacitor app without writing native code yourself. To learn more about the underlying SDKs, see the [official Google ML Kit documentation](https://developers.google.com/ml-kit).

### Are these ML Kit plugins free?

Yes. All ML Kit plugins listed here are open source and free to use.

### Which platforms do the plugins support?

The plugins support Android and iOS, with selected plugins also supporting the Web. The supported platforms are listed at the top of each plugin's documentation page.

### How do I get support?

For bugs and feature requests, open an issue on the plugin's GitHub repository. For dedicated help, see our [support options](/docs/support/).

## Next steps

- Browse all our [Capacitor plugins](https://capawesome.io/docs/sdks/capacitor/index.md).
- Explore [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) for Live Updates, Native Builds, and App Store Publishing.
- View the source on [GitHub](https://github.com/capawesome-team).

# Capacitor ML Kit Barcode Scanning Plugin

Unofficial Capacitor plugin for [ML Kit Barcode Scanning](https://developers.google.com/ml-kit/vision/barcode-scanning).[1](#fn:1)[2](#fn:2)

> [!TIP] Looking for Swift Package Manager (SPM) support, a themeable fullscreen scanner UI on both Android and iOS, or an [embedded camera view](https://capawesome.io/blog/capacitor-embedded-barcode-scanner/)? Take a look at our new [Barcode Scanner plugin](https://capawesome.io/docs/sdks/capacitor/barcode-scanner/) for [Capawesome Insiders](https://capawesome.io/insiders/) — a separate plugin that replaces ML Kit with AVFoundation and Vision on iOS.

## Features

- 🧩 Optional ready-to-use interface without webview customizations
- 🏎️ Extremely fast
- 📷 Scan multiple barcodes at once
- ⏺️ Define detection area
- 🏞️ Reading barcodes from images
- 🔦 Torch and Autofocus support
- 🔋 Supports Android, iOS and web

For a complete list of **supported barcodes**, see [BarcodeFormat](#barcodeformat).

## Use Cases

The Barcode Scanning plugin is typically used whenever an app needs to read a barcode or QR code with the camera, for example:

- **QR code scanning**: Read QR codes containing URLs, Wi-Fi credentials, contact details, or calendar events.
- **Product lookup and inventory**: Scan EAN and UPC product barcodes in retail, warehouse, or inventory apps.
- **Ticket and access validation**: Check in visitors by scanning tickets or badges encoded as Aztec, PDF417, or Data Matrix codes.
- **Identity capture**: Read driver licenses and ID cards that encode their data in a barcode.
- **Importing barcodes from images**: Read barcodes from existing photos, for example a screenshot of a QR code.

## 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     |

## Demo

A working example can be found here: <https://github.com/robingenz/capacitor-mlkit-plugin-demo>

| Android |
| ------- |
|         |

## Guides

- [Announcing the Capacitor ML Kit Barcode Scanning Plugin](https://capawesome.io/blog/announcing-the-capacitor-mlkit-barcode-scanner-plugin/)
- [How to build an Ionic Barcode Scanner with Capacitor](https://capawesome.io/blog/how-to-build-an-ionic-barcode-scanner-with-capacitor/)

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/barcode-scanning` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/barcode-scanning
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099). If you need SPM support, take a look at our new [Barcode Scanner plugin](https://capawesome.io/docs/sdks/capacitor/barcode-scanner/), which uses AVFoundation and Vision instead of ML Kit on iOS.

### Android

#### Permissions

This API requires the following permissions be added to your `AndroidManifest.xml` before the `application` tag:

```
<uses-permission android:name="android.permission.CAMERA" />
```

You also need to add the following meta data **in** the `application` tag in your `AndroidManifest.xml`:

```
<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="barcode_ui"/>
<!-- To use multiple models: android:value="face,model2,model3" -->
```

#### 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:

- `$androidxCameraCamera2Version` version of `androidx.camera:camera-camera2` (default: `1.5.2`)
- `$androidxCameraCoreVersion` version of `androidx.camera:camera-core` (default: `1.5.2`)
- `$androidxCameraLifecycleVersion` version of `androidx.camera:camera-lifecycle` (default: `1.5.2`)
- `$androidxCameraViewVersion` version of `androidx.camera:camera-view` (default: `1.5.2`)
- `$listenableFutureVersion` version of `com.google.guava:listenablefuture` (default: `1.0`)
- `$mlkitBarcodeScanningVersion` version of `com.google.mlkit:barcode-scanning` (default: `17.3.0`)
- `$playServicesCodeScannerVersion` version of `com.google.android.gms:play-services-code-scanner` (default: `16.1.0`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

### Usage Description

Add the `NSCameraUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why the app needs to use the camera:

```
+ <key>NSCameraUsageDescription</key>
+ <string>The app enables the scanning of various barcodes.</string>
```

### Web

#### Polyfill

This plugin uses the [Barcode Detection API](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API) to scan barcodes in the browser. This API is not yet supported in all browsers. You can check the compatibility [here](https://caniuse.com/mdn-api_barcodedetector). For this reason, we recommend installing the [barcode-detector](https://www.npmjs.com/package/barcode-detector) package for a better compatibility:

```
npm install barcode-detector
```

This package provides a polyfill that uses [ZXing-C++ WebAssembly](https://github.com/Sec-ant/zxing-wasm) under the hood. After installing the package, you just need to import the polyfill in your code:

```
import "barcode-detector/polyfill";
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following examples show how to scan barcodes with your own UI or the ready-to-use interface, control the torch and zoom, install the Google Barcode Scanner module, and manage camera permissions.

### Scan barcodes with your own UI

The `startScan(...)` method renders the camera behind the WebView so that you can build your own scanning UI on top of it. Add a listener to be notified about scanned barcodes and call `stopScan()` when you are done:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  // The camera is visible behind the WebView, so that you can customize the UI in the WebView.
  // However, this means that you have to hide all elements that should not be visible.
  // You can find an example in our demo repository.
  // In this case we set a class `barcode-scanner-active`, which then contains certain CSS rules for our app.
  document.querySelector('body')?.classList.add('barcode-scanner-active');

  // Add the `barcodeScanned` listener
  const listener = await BarcodeScanner.addListener(
    'barcodeScanned',
    async result => {
      console.log(result.barcode);
    },
  );

  // Start the barcode scanner
  await BarcodeScanner.startScan();
};

const stopScan = async () => {
  // Make all elements in the WebView visible again
  document.querySelector('body')?.classList.remove('barcode-scanner-active');

  // Remove all listeners
  await BarcodeScanner.removeAllListeners();

  // Stop the barcode scanner
  await BarcodeScanner.stopScan();
};
```

### Scan a single barcode

If you only need one result, remove the listener and stop the scan as soon as the first barcode is scanned:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const scanSingleBarcode = async () => {
  return new Promise(async resolve => {
    document.querySelector('body')?.classList.add('barcode-scanner-active');

    const listener = await BarcodeScanner.addListener(
      'barcodeScanned',
      async result => {
        await listener.remove();
        document
          .querySelector('body')
          ?.classList.remove('barcode-scanner-active');
        await BarcodeScanner.stopScan();
        resolve(result.barcode);
      },
    );

    await BarcodeScanner.startScan();
  });
};
```

### Scan with the ready-to-use interface

The `scan(...)` method opens a ready-to-use scanning interface without any WebView customization. Only available on Android and iOS. On Android, this requires the Google Barcode Scanner module (see [below](#install-the-google-barcode-scanner-module)), but no camera permission:

```
import { BarcodeScanner, BarcodeFormat } from '@capacitor-mlkit/barcode-scanning';

const scan = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    formats: [BarcodeFormat.QrCode],
    autoZoom: true,
  });
  return barcodes;
};
```

On Android, the system may destroy the app while the scanner is open. In this case, the promise will never resolve. Instead, the result is delivered through the `appRestoredResult` event of the [App plugin](https://capacitorjs.com/docs/apis/app#addlistenerapprestoredresult-) when the app is restored. If the app process was terminated, the scan result cannot be recovered and the event contains an error:

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

App.addListener('appRestoredResult', event => {
  if (event.pluginId !== 'BarcodeScanner' || event.methodName !== 'scan') {
    return;
  }
  if (event.success) {
    const barcodes = event.data.barcodes;
  } else {
    console.error(event.error?.message);
  }
});
```

### Check if the barcode scanner is supported

Check whether the device has a camera that can be used for barcode scanning:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const isSupported = async () => {
  const { supported } = await BarcodeScanner.isSupported();
  return supported;
};
```

### Control the torch

Use the [Capacitor Torch](https://capawesome.io/docs/sdks/capacitor/torch/) plugin to switch the flashlight on and off during a scan session:

```
import { Torch } from '@capawesome/capacitor-torch';

const enableTorch = async () => {
  await Torch.enable();
};

const disableTorch = async () => {
  await Torch.disable();
};

const toggleTorch = async () => {
  await Torch.toggle();
};

const isTorchEnabled = async () => {
  const { enabled } = await Torch.isEnabled();
  return enabled;
};

const isTorchAvailable = async () => {
  const { available } = await Torch.isAvailable();
  return available;
};
```

### Control the zoom

Set and read the zoom ratio of the camera. These methods are only available on Android and iOS:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const setZoomRatio = async () => {
  await BarcodeScanner.setZoomRatio({ zoomRatio: 0.5 });
};

const getZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getZoomRatio();
  return zoomRatio;
};

const getMinZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMinZoomRatio();
  return zoomRatio;
};

const getMaxZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMaxZoomRatio();
  return zoomRatio;
};
```

### Install the Google Barcode Scanner module

On Android, the `scan(...)` method requires the Google Barcode Scanner module. Check if it is available and install it if needed. The installation only starts with this call; the `googleBarcodeScannerModuleInstallProgress` event notifies you about the progress. Only available on Android:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const isGoogleBarcodeScannerModuleAvailable = async () => {
  const { available } =
    await BarcodeScanner.isGoogleBarcodeScannerModuleAvailable();
  return available;
};

const installGoogleBarcodeScannerModule = async () => {
  await BarcodeScanner.installGoogleBarcodeScannerModule();
};
```

### Check and request permissions

The `startScan(...)` method requires the camera permission. You can check and request it, and open the app settings so that the user can grant the permission manually:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const checkPermissions = async () => {
  const { camera } = await BarcodeScanner.checkPermissions();
  return camera;
};

const requestPermissions = async () => {
  const { camera } = await BarcodeScanner.requestPermissions();
  return camera;
};

const openSettings = async () => {
  await BarcodeScanner.openSettings();
};
```

### Hide all WebView elements during a scan

Since the camera is rendered behind the WebView when using `startScan(...)`, you have to hide all elements that should not be visible. An example of the CSS class `barcode-scanner-active` **with** Ionic Framework could be:

```
// Hide all elements
body.barcode-scanner-active {
  visibility: hidden;
  --background: transparent;
  --ion-background-color: transparent;
}

// Show only the barcode scanner modal
.barcode-scanner-modal {
  visibility: visible;
}

@media (prefers-color-scheme: dark) {
  .barcode-scanner-modal {
    --background: transparent;
    --ion-background-color: transparent;
  }
}
```

An example of the CSS class `barcode-scanner-active` **without** Ionic Framework could be:

```
// Hide all elements
body.barcode-scanner-active {
  visibility: hidden;
}

// Show only the barcode scanner modal
.barcode-scanner-modal {
  visibility: visible;
}
```

If you can't see the camera view, make sure all elements in the DOM are not visible or have a transparent background to debug the issue.

## API

- [`startScan(...)`](#startscan)
- [`stopScan()`](#stopscan)
- [`readBarcodesFromImage(...)`](#readbarcodesfromimage)
- [`scan(...)`](#scan)
- [`isSupported()`](#issupported)
- [`enableTorch()`](#enabletorch)
- [`disableTorch()`](#disabletorch)
- [`toggleTorch()`](#toggletorch)
- [`isTorchEnabled()`](#istorchenabled)
- [`isTorchAvailable()`](#istorchavailable)
- [`setZoomRatio(...)`](#setzoomratio)
- [`getZoomRatio()`](#getzoomratio)
- [`getMinZoomRatio()`](#getminzoomratio)
- [`getMaxZoomRatio()`](#getmaxzoomratio)
- [`openSettings()`](#opensettings)
- [`isGoogleBarcodeScannerModuleAvailable()`](#isgooglebarcodescannermoduleavailable)
- [`installGoogleBarcodeScannerModule()`](#installgooglebarcodescannermodule)
- [`checkPermissions()`](#checkpermissions)
- [`requestPermissions()`](#requestpermissions)
- [`addListener('barcodesScanned', ...)`](#addlistenerbarcodesscanned-)
- [`addListener('scanError', ...)`](#addlistenerscanerror-)
- [`addListener('googleBarcodeScannerModuleInstallProgress', ...)`](#addlistenergooglebarcodescannermoduleinstallprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### startScan(...)

```
startScan(options?: StartScanOptions | undefined) => Promise<void>
```

Start scanning for barcodes.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `StartScanOptions` |

**Since:** 0.0.1

______________________________________________________________________

### stopScan()

```
stopScan() => Promise<void>
```

Stop scanning for barcodes.

**Since:** 0.0.1

______________________________________________________________________

### readBarcodesFromImage(...)

```
readBarcodesFromImage(options: ReadBarcodesFromImageOptions) => Promise<ReadBarcodesFromImageResult>
```

Read barcodes from an image.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `ReadBarcodesFromImageOptions` |

**Returns:** `Promise<ReadBarcodesFromImageResult>`

**Since:** 0.0.1

______________________________________________________________________

### scan(...)

```
scan(options?: ScanOptions | undefined) => Promise<ScanResult>
```

Scan a barcode with a ready-to-use interface without WebView customization.

On **Android**, this method is only available on devices with Google Play Services installed. Therefore, no camera permission is required.

**Attention:** Before using this method on *Android*, first check if the Google [Barcode](#barcode) Scanner module is available by using `isGoogleBarcodeScannerModuleAvailable()`.

**Attention:** On *Android*, the system may destroy the app while the scanner is open. In this case, the promise will never resolve. Instead, the result is delivered through the `appRestoredResult` event of the [App plugin](https://capacitorjs.com/docs/apis/app#addlistenerapprestoredresult-) when the app is restored. If the app process was terminated, the scan result cannot be recovered and the event contains an error.

Only available on Android and iOS.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ScanOptions` |

**Returns:** `Promise<ScanResult>`

**Since:** 0.0.1

______________________________________________________________________

### isSupported()

```
isSupported() => Promise<IsSupportedResult>
```

Returns whether or not the barcode scanner is supported.

**Returns:** `Promise<IsSupportedResult>`

**Since:** 0.0.1

______________________________________________________________________

### enableTorch()

```
enableTorch() => Promise<void>
```

Enable camera's torch (flash) during a scan session.

Only available on Android and iOS.

**Since:** 7.2.0

______________________________________________________________________

### disableTorch()

```
disableTorch() => Promise<void>
```

Disable camera's torch (flash) during a scan session.

Only available on Android and iOS.

**Since:** 7.2.0

______________________________________________________________________

### toggleTorch()

```
toggleTorch() => Promise<void>
```

Toggle camera's torch (flash) during a scan session.

Only available on Android and iOS.

**Since:** 7.2.0

______________________________________________________________________

### isTorchEnabled()

```
isTorchEnabled() => Promise<IsTorchEnabledResult>
```

Returns whether or not the camera's torch (flash) is enabled.

Only available on Android and iOS.

**Returns:** `Promise<IsTorchEnabledResult>`

**Since:** 7.2.0

______________________________________________________________________

### isTorchAvailable()

```
isTorchAvailable() => Promise<IsTorchAvailableResult>
```

Returns whether or not the camera's torch (flash) is available.

Only available on Android and iOS.

**Returns:** `Promise<IsTorchAvailableResult>`

**Since:** 7.2.0

______________________________________________________________________

### setZoomRatio(...)

```
setZoomRatio(options: SetZoomRatioOptions) => Promise<void>
```

Set the zoom ratio of the camera.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `SetZoomRatioOptions` |

**Since:** 5.4.0

______________________________________________________________________

### getZoomRatio()

```
getZoomRatio() => Promise<GetZoomRatioResult>
```

Get the zoom ratio of the camera.

Only available on Android and iOS.

**Returns:** `Promise<GetZoomRatioResult>`

**Since:** 5.4.0

______________________________________________________________________

### getMinZoomRatio()

```
getMinZoomRatio() => Promise<GetMinZoomRatioResult>
```

Get the minimum zoom ratio of the camera.

Only available on Android and iOS.

**Returns:** `Promise<GetMinZoomRatioResult>`

**Since:** 5.4.0

______________________________________________________________________

### getMaxZoomRatio()

```
getMaxZoomRatio() => Promise<GetMaxZoomRatioResult>
```

Get the maximum zoom ratio of the camera.

Only available on Android and iOS.

**Returns:** `Promise<GetMaxZoomRatioResult>`

**Since:** 5.4.0

______________________________________________________________________

### openSettings()

```
openSettings() => Promise<void>
```

Open the settings of the app so that the user can grant the camera permission.

Only available on Android and iOS.

**Since:** 0.0.1

______________________________________________________________________

### isGoogleBarcodeScannerModuleAvailable()

```
isGoogleBarcodeScannerModuleAvailable() => Promise<IsGoogleBarcodeScannerModuleAvailableResult>
```

Check if the Google [Barcode](#barcode) Scanner module is available.

If the Google [Barcode](#barcode) Scanner module is not available, you can install it by using `installGoogleBarcodeScannerModule()`.

Only available on Android.

**Returns:** `Promise<IsGoogleBarcodeScannerModuleAvailableResult>`

**Since:** 5.1.0

______________________________________________________________________

### installGoogleBarcodeScannerModule()

```
installGoogleBarcodeScannerModule() => Promise<void>
```

Install the Google [Barcode](#barcode) Scanner module.

**Attention**: This only starts the installation. The `googleBarcodeScannerModuleInstallProgress` event listener will notify you when the installation is complete.

Only available on Android.

**Since:** 5.1.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check camera permission.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request camera permission.

**Returns:** `Promise<PermissionStatus>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('barcodesScanned', ...)

```
addListener(eventName: 'barcodesScanned', listenerFunc: (event: BarcodesScannedEvent) => void) => Promise<PluginListenerHandle>
```

Called when barcodes are scanned.

| Param              | Type                                    |
| ------------------ | --------------------------------------- |
| **`eventName`**    | `'barcodesScanned'`                     |
| **`listenerFunc`** | `(event: BarcodesScannedEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 6.2.0

______________________________________________________________________

### addListener('scanError', ...)

```
addListener(eventName: 'scanError', listenerFunc: (event: ScanErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during the scan.

Available on Android and iOS.

| Param              | Type                              |
| ------------------ | --------------------------------- |
| **`eventName`**    | `'scanError'`                     |
| **`listenerFunc`** | `(event: ScanErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 0.0.1

______________________________________________________________________

### addListener('googleBarcodeScannerModuleInstallProgress', ...)

```
addListener(eventName: 'googleBarcodeScannerModuleInstallProgress', listenerFunc: (event: GoogleBarcodeScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when the Google [Barcode](#barcode) Scanner module is installed.

Available on Android.

| Param              | Type                                                              |
| ------------------ | ----------------------------------------------------------------- |
| **`eventName`**    | `'googleBarcodeScannerModuleInstallProgress'`                     |
| **`listenerFunc`** | `(event: GoogleBarcodeScannerModuleInstallProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 5.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### StartScanOptions

| Prop                                 | Type               | Description                                                                                                                                                                                                           | Default                  | Since |
| ------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |
| **`formats`**                        | `BarcodeFormat[]`  | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. Only available on Android and iOS.                                                                                           |                          | 0.0.1 |
| **`lensFacing`**                     | `LensFacing`       | Configure the camera (front or back) to use.                                                                                                                                                                          |                          | 0.0.1 |
| **`resolution`**                     | `Resolution`       | Configure the resolution of the captured image that is used for barcode scanning. If the resolution is not supported by the device, the closest supported resolution will be used. Only available on Android and iOS. | `Resolution['1280x720']` | 7.0.0 |
| **`enableMultitaskingCameraAccess`** | `boolean`          | Allow camera usage on iPad while in multitasking mode. Only available on iOS (16.0+).                                                                                                                                 | `false`                  | 7.5.0 |
| **`videoElement`**                   | `HTMLVideoElement` | The HTML video element to use for the camera preview. Only available on web.                                                                                                                                          |                          | 7.1.0 |

#### ReadBarcodesFromImageResult

| Prop           | Type        | Description            | Since |
| -------------- | ----------- | ---------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The detected barcodes. | 0.0.1 |

#### Barcode

| Prop                | Type                                                                       | Description                                                                                                                                                                        | Since |
| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bytes`**         | `number[]`                                                                 | Raw bytes as it was encoded in the barcode.                                                                                                                                        | 0.0.1 |
| **`calendarEvent`** | `BarcodeCalendarEvent`                                                     | Calendar event info.                                                                                                                                                               | 7.0.0 |
| **`contactInfo`**   | `BarcodeContactInfo`                                                       | Person's or organization's business card.                                                                                                                                          | 7.0.0 |
| **`cornerPoints`**  | `[[number, number], [number, number], [number, number], [number, number]]` | The four corner points of the barcode in clockwise order starting with top-left. This property is currently only supported by the `startScan(...)` method.                         | 0.0.1 |
| **`displayValue`**  | `string`                                                                   | The barcode value in a human readable format.                                                                                                                                      | 0.0.1 |
| **`driverLicense`** | `BarcodeDriverLicense`                                                     | Driver license or ID card.                                                                                                                                                         | 7.0.0 |
| **`email`**         | `BarcodeEmail`                                                             | An email message from a 'MAILTO:'.                                                                                                                                                 | 7.0.0 |
| **`format`**        | `BarcodeFormat`                                                            | The barcode format.                                                                                                                                                                | 0.0.1 |
| **`geoPoint`**      | `BarcodeGeoPoint`                                                          | GPS coordinates from a 'GEO:'.                                                                                                                                                     | 7.0.0 |
| **`phone`**         | `BarcodePhone`                                                             | Phone number info.                                                                                                                                                                 | 7.0.0 |
| **`rawValue`**      | `string`                                                                   | The barcode value in a machine readable format. This value is only available if the barcode is encoded in the UTF-8 character set. Otherwise, the `bytes` property should be used. | 0.0.1 |
| **`sms`**           | `BarcodeSms`                                                               | A sms message from a 'SMS:'.                                                                                                                                                       | 7.0.0 |
| **`urlBookmark`**   | `BarcodeUrlBookmark`                                                       | A URL and title from a 'MEBKM:'.                                                                                                                                                   | 7.0.0 |
| **`valueType`**     | `BarcodeValueType`                                                         | The barcode value type.                                                                                                                                                            | 0.0.1 |
| **`wifi`**          | `BarcodeWifi`                                                              | A wifi network parameters from a 'WIFI:'.                                                                                                                                          | 7.0.0 |

#### BarcodeCalendarEvent

| Prop              | Type     | Description                              | Since |
| ----------------- | -------- | ---------------------------------------- | ----- |
| **`description`** | `string` | The event description.                   | 7.0.0 |
| **`end`**         | `string` | The event end date as ISO 8601 string.   | 7.0.0 |
| **`location`**    | `string` | The event location.                      | 7.0.0 |
| **`organizer`**   | `string` | The event organizer.                     | 7.0.0 |
| **`start`**       | `string` | The event start date as ISO 8601 string. | 7.0.0 |
| **`status`**      | `string` | The event status.                        | 7.0.0 |
| **`summary`**     | `string` | The event summary.                       | 7.0.0 |

#### BarcodeContactInfo

| Prop               | Type             | Description                 | Since |
| ------------------ | ---------------- | --------------------------- | ----- |
| **`addresses`**    | `Address[]`      | The contact's addresses.    | 7.0.0 |
| **`emails`**       | `BarcodeEmail[]` | The contact's emails.       | 7.0.0 |
| **`personName`**   | `PersonName`     | The contact's name.         | 7.0.0 |
| **`organization`** | `string`         | The contact's organization. | 7.0.0 |
| **`phones`**       | `BarcodePhone[]` | The contact's phones.       | 7.0.0 |
| **`title`**        | `string`         | The contact's title.        | 7.0.0 |
| **`urls`**         | `string[]`       | The contact's urls.         | 7.0.0 |

#### Address

| Prop               | Type          | Description                                         | Since |
| ------------------ | ------------- | --------------------------------------------------- | ----- |
| **`addressLines`** | `string[]`    | Formatted address, multiple lines when appropriate. | 7.0.0 |
| **`type`**         | `AddressType` | [Address](#address) type.                           | 7.0.0 |

#### BarcodeEmail

| Prop          | Type              | Description             | Since |
| ------------- | ----------------- | ----------------------- | ----- |
| **`address`** | `string`          | The email address.      | 7.0.0 |
| **`body`**    | `string`          | The email body.         | 7.0.0 |
| **`subject`** | `string`          | The email subject.      | 7.0.0 |
| **`type`**    | `EmailFormatType` | The email address type. | 7.0.0 |

#### PersonName

| Prop                | Type     | Description                                                                          | Since |
| ------------------- | -------- | ------------------------------------------------------------------------------------ | ----- |
| **`first`**         | `string` | First name.                                                                          | 7.0.0 |
| **`formattedName`** | `string` | The formatted name.                                                                  | 7.0.0 |
| **`last`**          | `string` | Last name.                                                                           | 7.0.0 |
| **`middle`**        | `string` | Middle name.                                                                         | 7.0.0 |
| **`prefix`**        | `string` | Name prefix.                                                                         | 7.0.0 |
| **`pronunciation`** | `string` | Text string to be set as the kana name in the phonebook. Used for Japanese contacts. | 7.0.0 |
| **`suffix`**        | `string` | Name suffix.                                                                         | 7.0.0 |

#### BarcodePhone

| Prop         | Type              | Description            | Since |
| ------------ | ----------------- | ---------------------- | ----- |
| **`number`** | `string`          | The phone number.      | 7.0.0 |
| **`type`**   | `PhoneFormatType` | The phone number type. | 7.0.0 |

#### BarcodeDriverLicense

| Prop                 | Type     | Description                                        | Since |
| -------------------- | -------- | -------------------------------------------------- | ----- |
| **`addressCity`**    | `string` | City of holder's address.                          | 7.0.0 |
| **`addressState`**   | `string` | State of holder's address.                         | 7.0.0 |
| **`addressStreet`**  | `string` | Street of holder's address.                        | 7.0.0 |
| **`addressZip`**     | `string` | Postal code of holder's address.                   | 7.0.0 |
| **`birthDate`**      | `string` | Birthdate of the holder.                           | 7.0.0 |
| **`documentType`**   | `string` | "DL" for driver's licenses, "ID" for ID cards.     | 7.0.0 |
| **`expiryDate`**     | `string` | Expiration date of the license.                    | 7.0.0 |
| **`firstName`**      | `string` | Holder's first name.                               | 7.0.0 |
| **`gender`**         | `string` | Holder's gender.                                   | 7.0.0 |
| **`issueDate`**      | `string` | Issue date of the license.                         | 7.0.0 |
| **`issuingCountry`** | `string` | ISO 3166-1 alpha-3 code in which DL/ID was issued. | 7.0.0 |
| **`lastName`**       | `string` | Holder's last name.                                | 7.0.0 |
| **`licenseNumber`**  | `string` | Driver license ID number.                          | 7.0.0 |
| **`middleName`**     | `string` | Holder's middle name.                              | 7.0.0 |

#### BarcodeGeoPoint

| Prop            | Type     | Description | Since |
| --------------- | -------- | ----------- | ----- |
| **`latitude`**  | `number` | Latitude.   | 7.0.0 |
| **`longitude`** | `number` | Longitude.  | 7.0.0 |

#### BarcodeSms

| Prop              | Type     | Description                     | Since |
| ----------------- | -------- | ------------------------------- | ----- |
| **`phoneNumber`** | `string` | The phone number of the sms.    | 7.0.0 |
| **`message`**     | `string` | The message content of the sms. | 7.0.0 |

#### BarcodeUrlBookmark

| Prop        | Type     | Description                | Since |
| ----------- | -------- | -------------------------- | ----- |
| **`url`**   | `string` | The URL of the bookmark.   | 7.0.0 |
| **`title`** | `string` | The title of the bookmark. | 7.0.0 |

#### BarcodeWifi

| Prop                 | Type                 | Description                   | Since |
| -------------------- | -------------------- | ----------------------------- | ----- |
| **`encryptionType`** | `WifiEncryptionType` | Encryption type of the WI-FI. | 7.0.0 |
| **`password`**       | `string`             | Password of the WI-FI.        | 7.0.0 |
| **`ssid`**           | `string`             | SSID of the WI-FI.            | 7.0.0 |

#### ReadBarcodesFromImageOptions

| Prop          | Type              | Description                                                                              | Since |
| ------------- | ----------------- | ---------------------------------------------------------------------------------------- | ----- |
| **`blob`**    | `Blob`            | The blob instance of the image file. Only available on Web.                              | 7.4.0 |
| **`formats`** | `BarcodeFormat[]` | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |
| **`path`**    | `string`          | The local path to the image file. Only available on Android and iOS.                     | 0.0.1 |

#### ScanResult

| Prop           | Type        | Description            | Since |
| -------------- | ----------- | ---------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The detected barcodes. | 0.0.1 |

#### ScanOptions

| Prop           | Type              | Description                                                                              | Since |
| -------------- | ----------------- | ---------------------------------------------------------------------------------------- | ----- |
| **`formats`**  | `BarcodeFormat[]` | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |
| **`autoZoom`** | `boolean`         | Toggle the auto zoom feature.                                                            | 7.4.0 |

#### IsSupportedResult

| Prop            | Type      | Description                                                                             | Since |
| --------------- | --------- | --------------------------------------------------------------------------------------- | ----- |
| **`supported`** | `boolean` | Whether or not the barcode scanner is supported by checking if the device has a camera. | 0.0.1 |

#### IsTorchEnabledResult

| Prop          | Type      | Description                          | Since |
| ------------- | --------- | ------------------------------------ | ----- |
| **`enabled`** | `boolean` | Whether or not the torch is enabled. | 0.0.1 |

#### IsTorchAvailableResult

| Prop            | Type      | Description                            | Since |
| --------------- | --------- | -------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not the torch is available. | 0.0.1 |

#### SetZoomRatioOptions

| Prop            | Type     | Description            | Since |
| --------------- | -------- | ---------------------- | ----- |
| **`zoomRatio`** | `number` | The zoom ratio to set. | 5.4.0 |

#### GetZoomRatioResult

| Prop            | Type     | Description     | Since |
| --------------- | -------- | --------------- | ----- |
| **`zoomRatio`** | `number` | The zoom ratio. | 5.4.0 |

#### GetMinZoomRatioResult

| Prop            | Type     | Description             | Since |
| --------------- | -------- | ----------------------- | ----- |
| **`zoomRatio`** | `number` | The minimum zoom ratio. | 5.4.0 |

#### GetMaxZoomRatioResult

| Prop            | Type     | Description             | Since |
| --------------- | -------- | ----------------------- | ----- |
| **`zoomRatio`** | `number` | The maximum zoom ratio. | 5.4.0 |

#### IsGoogleBarcodeScannerModuleAvailableResult

| Prop            | Type      | Description                                                                | Since |
| --------------- | --------- | -------------------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not the Google [Barcode](#barcode) Scanner module is available. | 5.1.0 |

#### PermissionStatus

| Prop         | Type                    | Since |
| ------------ | ----------------------- | ----- |
| **`camera`** | `CameraPermissionState` | 0.0.1 |

#### PluginListenerHandle

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

#### BarcodesScannedEvent

| Prop           | Type        | Description            | Since |
| -------------- | ----------- | ---------------------- | ----- |
| **`barcodes`** | `Barcode[]` | The detected barcodes. | 6.2.0 |

#### ScanErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 0.0.1 |

#### GoogleBarcodeScannerModuleInstallProgressEvent

| Prop           | Type                                     | Description                                                    | Since |
| -------------- | ---------------------------------------- | -------------------------------------------------------------- | ----- |
| **`state`**    | `GoogleBarcodeScannerModuleInstallState` | The current state of the installation.                         | 5.1.0 |
| **`progress`** | `number`                                 | The progress of the installation in percent between 0 and 100. | 5.1.0 |

### Type Aliases

#### CameraPermissionState

`PermissionState | 'limited'`

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### Enums

#### BarcodeFormat

| Members          | Value           | Description                        | Since |
| ---------------- | --------------- | ---------------------------------- | ----- |
| **`Aztec`**      | `'AZTEC'`       | Only available on Android and iOS. | 0.0.1 |
| **`Codabar`**    | `'CODABAR'`     | Only available on Android and iOS. | 0.0.1 |
| **`Code39`**     | `'CODE_39'`     | Only available on Android and iOS. | 0.0.1 |
| **`Code93`**     | `'CODE_93'`     | Only available on Android and iOS. | 0.0.1 |
| **`Code128`**    | `'CODE_128'`    | Only available on Android and iOS. | 0.0.1 |
| **`DataMatrix`** | `'DATA_MATRIX'` | Only available on Android and iOS. | 0.0.1 |
| **`Ean8`**       | `'EAN_8'`       | Only available on Android and iOS. | 0.0.1 |
| **`Ean13`**      | `'EAN_13'`      | Only available on Android and iOS. | 0.0.1 |
| **`Itf`**        | `'ITF'`         | Only available on Android and iOS. | 0.0.1 |
| **`Pdf417`**     | `'PDF_417'`     | Only available on Android and iOS. | 0.0.1 |
| **`QrCode`**     | `'QR_CODE'`     | Only available on Android and iOS. | 0.0.1 |
| **`UpcA`**       | `'UPC_A'`       | Only available on Android and iOS. | 0.0.1 |
| **`UpcE`**       | `'UPC_E'`       | Only available on Android and iOS. | 0.0.1 |

#### LensFacing

| Members     | Value     | Since |
| ----------- | --------- | ----- |
| **`Front`** | `'FRONT'` | 0.0.1 |
| **`Back`**  | `'BACK'`  | 0.0.1 |

#### Resolution

| Members           | Value | Since |
| ----------------- | ----- | ----- |
| **`'640x480'`**   | `0`   | 7.0.0 |
| **`'1280x720'`**  | `1`   | 7.0.0 |
| **`'1920x1080'`** | `2`   | 7.0.0 |
| **`'3840x2160'`** | `3`   | 7.2.0 |

#### AddressType

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`HOME`**    | `0`   | 7.0.0 |
| **`UNKNOWN`** | `1`   | 7.0.0 |
| **`WORK`**    | `2`   | 7.0.0 |

#### EmailFormatType

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`HOME`**    | `0`   | 7.0.0 |
| **`UNKNOWN`** | `1`   | 7.0.0 |
| **`WORK`**    | `2`   | 7.0.0 |

#### PhoneFormatType

| Members       | Value | Since |
| ------------- | ----- | ----- |
| **`FAX`**     | `0`   | 7.0.0 |
| **`HOME`**    | `1`   | 7.0.0 |
| **`MOBILE`**  | `2`   | 7.0.0 |
| **`UNKNOWN`** | `3`   | 7.0.0 |
| **`WORK`**    | `4`   | 7.0.0 |

#### BarcodeValueType

| Members              | Value               | Since |
| -------------------- | ------------------- | ----- |
| **`CalendarEvent`**  | `'CALENDAR_EVENT'`  | 0.0.1 |
| **`ContactInfo`**    | `'CONTACT_INFO'`    | 0.0.1 |
| **`DriversLicense`** | `'DRIVERS_LICENSE'` | 0.0.1 |
| **`Email`**          | `'EMAIL'`           | 0.0.1 |
| **`Geo`**            | `'GEO'`             | 0.0.1 |
| **`Isbn`**           | `'ISBN'`            | 0.0.1 |
| **`Phone`**          | `'PHONE'`           | 0.0.1 |
| **`Product`**        | `'PRODUCT'`         | 0.0.1 |
| **`Sms`**            | `'SMS'`             | 0.0.1 |
| **`Text`**           | `'TEXT'`            | 0.0.1 |
| **`Url`**            | `'URL'`             | 0.0.1 |
| **`Wifi`**           | `'WIFI'`            | 0.0.1 |
| **`Unknown`**        | `'UNKNOWN'`         | 0.0.1 |

#### WifiEncryptionType

| Members    | Value | Since |
| ---------- | ----- | ----- |
| **`OPEN`** | `1`   | 7.0.0 |
| **`WEP`**  | `2`   | 7.0.0 |
| **`WPA`**  | `3`   | 7.0.0 |

#### GoogleBarcodeScannerModuleInstallState

| Members               | Value | Since |
| --------------------- | ----- | ----- |
| **`UNKNOWN`**         | `0`   | 5.1.0 |
| **`PENDING`**         | `1`   | 5.1.0 |
| **`DOWNLOADING`**     | `2`   | 5.1.0 |
| **`CANCELED`**        | `3`   | 5.1.0 |
| **`COMPLETED`**       | `4`   | 5.1.0 |
| **`FAILED`**          | `5`   | 5.1.0 |
| **`INSTALLING`**      | `6`   | 5.1.0 |
| **`DOWNLOAD_PAUSED`** | `7`   | 5.1.0 |

## FAQ

### What is the difference between `startScan` and `scan`?

The `startScan(...)` method renders the camera behind the WebView so that you can build a completely custom scanning UI, but it requires you to hide all WebView elements that should not be visible (see the [usage example](#hide-all-webview-elements-during-a-scan)). The `scan(...)` method opens a ready-to-use interface without any WebView customization and is only available on Android and iOS. On Android, `scan(...)` requires the Google Barcode Scanner module but no camera permission.

### Why is the camera view not visible during a scan?

When using `startScan(...)`, the camera is rendered behind the WebView. If any element in the DOM is visible or has an opaque background, it covers the camera view. Make sure to hide all elements or give them a transparent background, as shown in the [usage example](#hide-all-webview-elements-during-a-scan). If hiding all elements is impractical in your app (for example with Ionic modals or page transitions), the [Capacitor Barcode Scanner plugin](https://capawesome.io/docs/sdks/capacitor/barcode-scanner/) offers an [embedded camera view](https://capawesome.io/blog/capacitor-embedded-barcode-scanner/) that is rendered above the web view instead.

### Which barcode formats are supported?

The plugin supports 13 barcode formats on Android and iOS, including QR Code, Aztec, Codabar, Code 39, Code 93, Code 128, Data Matrix, EAN-8, EAN-13, ITF, PDF417, UPC-A, and UPC-E. See [BarcodeFormat](#barcodeformat) for the complete list. You can improve the scanning speed by restricting the formats via the `formats` option.

### Does the plugin work in the browser?

Yes, on the Web the plugin uses the [Barcode Detection API](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API), which is not yet supported in all browsers. For better compatibility, it is recommended to install the [barcode-detector](https://www.npmjs.com/package/barcode-detector) polyfill as described in the [Installation](#installation) section.

### Do I need the camera permission to scan barcodes?

The `startScan(...)` method requires the camera permission, which is why you have to declare the `CAMERA` permission in your `AndroidManifest.xml` and add the `NSCameraUsageDescription` key to your `Info.plist`. The `scan(...)` method on Android is provided by Google Play Services and therefore requires no camera permission.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Torch](https://capawesome.io/docs/sdks/capacitor/torch/): Switch the flashlight on and off during a scan session.
- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Let the user select an image from the file system or gallery to read barcodes from.
- [ML Kit Document Scanner](https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner/): Scan physical documents with ML Kit Document Scanner.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/barcode-scanning/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/barcode-scanning/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")
1. `QR Code` is a registered trademark of DENSO WAVE INCORPORATED. [↩](#fnref:2 "Jump back to footnote 2 in the text")

# Capacitor ML Kit Digital Ink Recognition Plugin

Unofficial Capacitor plugin for [ML Kit Digital Ink Recognition](https://developers.google.com/ml-kit/vision/digital-ink-recognition).[1](#fn:1)

## Use Cases

The Digital Ink Recognition plugin recognizes handwritten text and hand-drawn shapes from stroke coordinates directly on the device, for example:

- **Handwriting input**: Let users write text with their finger or a stylus instead of typing.
- **Note taking**: Convert handwritten notes into digital text.
- **Form filling**: Recognize handwritten input in signature or annotation fields.
- **Sketch recognition**: Classify hand-drawn shapes and emojis with the special gesture models.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/digital-ink-recognition` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/digital-ink-recognition
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitDigitalInkRecognitionVersion` version of `com.google.mlkit:digital-ink-recognition` (default: `19.0.0`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

Before any ink can be recognized, the model for the desired language must be downloaded:

```
import { DigitalInkRecognition } from '@capacitor-mlkit/digital-ink-recognition';

const downloadModel = async () => {
  await DigitalInkRecognition.downloadModel({
    languageTag: 'en-US',
  });
};
```

The plugin does not render anything. Capture the strokes with your own drawing surface, for example a canvas with pointer events:

```
import type { Stroke, StrokePoint } from '@capacitor-mlkit/digital-ink-recognition';

const canvas = document.querySelector('canvas');

const strokes: Stroke[] = [];
let currentPoints: StrokePoint[] | undefined;

canvas.addEventListener('pointerdown', event => {
  currentPoints = [{ x: event.offsetX, y: event.offsetY, t: Date.now() }];
});
canvas.addEventListener('pointermove', event => {
  currentPoints?.push({ x: event.offsetX, y: event.offsetY, t: Date.now() });
});
canvas.addEventListener('pointerup', event => {
  if (currentPoints) {
    currentPoints.push({ x: event.offsetX, y: event.offsetY, t: Date.now() });
    strokes.push({ points: currentPoints });
    currentPoints = undefined;
  }
});
```

Finally, pass the captured strokes to the `recognize(...)` method:

```
const recognize = async () => {
  const { candidates } = await DigitalInkRecognition.recognize({
    languageTag: 'en-US',
    strokes,
    writingArea: {
      width: canvas.width,
      height: canvas.height,
    },
  });
  return candidates;
};
```

Besides the language models, there are also special models for recognizing hand-drawn shapes (`zxx-Zsym-x-autodraw`) and emojis (`zxx-Zsym-x-emoji`).

## API

- [`deleteDownloadedModel(...)`](#deletedownloadedmodel)
- [`downloadModel(...)`](#downloadmodel)
- [`getDownloadedModels()`](#getdownloadedmodels)
- [`recognize(...)`](#recognize)
- [Interfaces](#interfaces)

### deleteDownloadedModel(...)

```
deleteDownloadedModel(options: DeleteDownloadedModelOptions) => Promise<void>
```

Delete the downloaded model for the given language.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `DeleteDownloadedModelOptions` |

**Since:** 8.2.0

______________________________________________________________________

### downloadModel(...)

```
downloadModel(options: DownloadModelOptions) => Promise<void>
```

Download a model for the given language.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `DownloadModelOptions` |

**Since:** 8.2.0

______________________________________________________________________

### getDownloadedModels()

```
getDownloadedModels() => Promise<GetDownloadedModelsResult>
```

Get the languages for which a model has been downloaded.

Only available on Android and iOS.

**Returns:** `Promise<GetDownloadedModelsResult>`

**Since:** 8.2.0

______________________________________________________________________

### recognize(...)

```
recognize(options: RecognizeOptions) => Promise<RecognizeResult>
```

Recognize the handwritten text or hand-drawn shapes in the given strokes.

The model for the given language must be downloaded before calling this method, otherwise the call is rejected with the error code `MODEL_NOT_DOWNLOADED`.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `RecognizeOptions` |

**Returns:** `Promise<RecognizeResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### DeleteDownloadedModelOptions

| Prop              | Type     | Description                                     | Since |
| ----------------- | -------- | ----------------------------------------------- | ----- |
| **`languageTag`** | `string` | The BCP-47 language tag of the model to delete. | 8.2.0 |

#### DownloadModelOptions

| Prop              | Type     | Description                                                                                                                                                                                                                                                                                    | Since |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`languageTag`** | `string` | The BCP-47 language tag of the model to download. See the [supported languages](https://developers.google.com/ml-kit/vision/digital-ink-recognition/base-models) for a list of available models. The special tag `zxx-Zsym-x-autodraw` identifies the model for recognizing hand-drawn shapes. | 8.2.0 |

#### GetDownloadedModelsResult

| Prop               | Type       | Description                                        | Since |
| ------------------ | ---------- | -------------------------------------------------- | ----- |
| **`languageTags`** | `string[]` | The BCP-47 language tags of the downloaded models. | 8.2.0 |

#### RecognizeResult

| Prop             | Type                     | Description                                               | Since |
| ---------------- | ------------------------ | --------------------------------------------------------- | ----- |
| **`candidates`** | `RecognitionCandidate[]` | The recognition candidates ordered by descending quality. | 8.2.0 |

#### RecognitionCandidate

| Prop        | Type     | Description                                                                                            | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------ | ----- |
| **`text`**  | `string` | The recognized text.                                                                                   | 8.2.0 |
| **`score`** | `number` | The score of the candidate. Lower scores indicate better results. The score is not set for all models. | 8.2.0 |

#### RecognizeOptions

| Prop                 | Type          | Description                                                                                                                                                                                         | Default | Since |
| -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`languageTag`**    | `string`      | The BCP-47 language tag of the model to use for recognition.                                                                                                                                        |         | 8.2.0 |
| **`strokes`**        | `Stroke[]`    | The strokes to recognize.                                                                                                                                                                           |         | 8.2.0 |
| **`maxResultCount`** | `number`      | The maximum number of recognition candidates to return.                                                                                                                                             | `5`     | 8.2.0 |
| **`preContext`**     | `string`      | The characters immediately preceding the strokes to improve recognition accuracy. A good rule of thumb is to provide as many characters as possible, up to around 20 characters (including spaces). |         | 8.2.0 |
| **`writingArea`**    | `WritingArea` | The size of the writing area to improve recognition accuracy.                                                                                                                                       |         | 8.2.0 |

#### Stroke

| Prop         | Type            | Description                                                        | Since |
| ------------ | --------------- | ------------------------------------------------------------------ | ----- |
| **`points`** | `StrokePoint[]` | The points of the stroke in the order in which they were captured. | 8.2.0 |

#### StrokePoint

| Prop    | Type     | Description                                                                                      | Since |
| ------- | -------- | ------------------------------------------------------------------------------------------------ | ----- |
| **`x`** | `number` | The horizontal coordinate of the point. Increases to the right.                                  | 8.2.0 |
| **`y`** | `number` | The vertical coordinate of the point. Increases going downward.                                  | 8.2.0 |
| **`t`** | `number` | The timestamp of the point in milliseconds. Providing a timestamp improves recognition accuracy. | 8.2.0 |

#### WritingArea

| Prop         | Type     | Description                                                                                           | Since |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------- | ----- |
| **`width`**  | `number` | The width of the writing area. The unit must be the same as the one used for the stroke coordinates.  | 8.2.0 |
| **`height`** | `number` | The height of the writing area. The unit must be the same as the one used for the stroke coordinates. | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. The recognition and model management methods are only available on Android and iOS, so there is no web implementation.

### Which languages are supported?

Models are available for [over 300 languages](https://developers.google.com/ml-kit/vision/digital-ink-recognition/base-models) identified by BCP-47 language tags. There are also special models for recognizing hand-drawn shapes (`zxx-Zsym-x-autodraw`) and emojis (`zxx-Zsym-x-emoji`).

### Do I need to download a model?

Yes. A model must be downloaded for each language before it can be used with the `recognize(...)` method. If the model has not been downloaded yet, the call is rejected with the error code `MODEL_NOT_DOWNLOADED`.

### How do I capture the strokes?

The plugin does not provide a drawing surface. Capture the pointer events on your own canvas and pass the collected strokes to the `recognize(...)` method (see [Usage](#usage)).

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Translate the recognized text into other languages.
- [Language Identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/): Identify the language of the recognized text.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/digital-ink-recognition/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/digital-ink-recognition/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Document Scanner Plugin

Unofficial Capacitor plugin for [ML Kit Document Scanner](https://developers.google.com/ml-kit/vision/doc-scanner).[1](#fn:1)

## Use Cases

The Document Scanner plugin is typically used whenever an app needs to digitize paper documents with the camera, for example:

- **Receipt and expense capture**: Let users scan receipts and invoices as JPEG images or PDF files for expense tracking.
- **Document archiving**: Digitize contracts, letters, and other paperwork into multi-page PDF documents.
- **Form submission**: Let users scan and submit signed forms or supporting documents in your app.
- **Clean document photos**: Use the ML-enabled image cleaning capabilities to remove stains and fingers from scanned pages.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/document-scanner` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/document-scanner
npx cap sync
```

### Android

#### 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:

- `$mlkitDocumentScannerVersion` version of `com.google.android.gms:play-services-mlkit-document-scanner` (default: `16.0.0`)

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

## Usage

The following examples show how to scan a document and how to check and install the Google Document Scanner module.

### Scan a document

Start the document scanning process, which opens the ML Kit Document Scanner UI. You can allow gallery imports, limit the number of pages, and choose the result formats and scanner mode. Only available on Android:

```
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const scanDocument = async () => {
  const result = await DocumentScanner.scanDocument({
    galleryImportAllowed: true,
    pageLimit: 5,
    resultFormats: 'JPEG_PDF',
    scannerMode: 'FULL',
  });

  console.log('Scanned images:', result.scannedImages);
  console.log('PDF info:', result.pdf);
};
```

### Check and install the Google Document Scanner module

The document scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services. Check if the module is available and install it if needed. The installation only starts with this call; the `googleDocumentScannerModuleInstallProgress` event notifies you about the progress. Only available on Android:

```
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const isGoogleDocumentScannerModuleAvailable = async () => {
  const result = await DocumentScanner.isGoogleDocumentScannerModuleAvailable();
  console.log('Is Google Document Scanner module available:', result.available);
};

const installGoogleDocumentScannerModule = async () => {
  await DocumentScanner.installGoogleDocumentScannerModule();
  console.log('Google Document Scanner module installation started.');
};

DocumentScanner.addListener('googleDocumentScannerModuleInstallProgress', (event) => {
  console.log('Installation progress:', event.progress, '%');
  console.log('Current state:', event.state);
});
```

## API

- [`scanDocument(...)`](#scandocument)
- [`isGoogleDocumentScannerModuleAvailable()`](#isgoogledocumentscannermoduleavailable)
- [`installGoogleDocumentScannerModule()`](#installgoogledocumentscannermodule)
- [`addListener('googleDocumentScannerModuleInstallProgress', ...)`](#addlistenergoogledocumentscannermoduleinstallprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### scanDocument(...)

```
scanDocument(options: ScanOptions) => Promise<ScanResult>
```

Starts the document scanning process.

Only available on Android.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `ScanOptions` |

**Returns:** `Promise<ScanResult>`

**Since:** 7.3.0

______________________________________________________________________

### isGoogleDocumentScannerModuleAvailable()

```
isGoogleDocumentScannerModuleAvailable() => Promise<IsGoogleDocumentScannerModuleAvailableResult>
```

Check if the Google Document Scanner module is available.

If the Google Document Scanner module is not available, you can install it by using `installGoogleDocumentScannerModule()`.

Only available on Android.

**Returns:** `Promise<IsGoogleDocumentScannerModuleAvailableResult>`

**Since:** 7.3.0

______________________________________________________________________

### installGoogleDocumentScannerModule()

```
installGoogleDocumentScannerModule() => Promise<void>
```

Install the Google Document Scanner module.

**Attention**: This only starts the installation. The `googleDocumentScannerModuleInstallProgress` event listener will notify you when the installation is complete.

Only available on Android.

**Since:** 7.3.0

______________________________________________________________________

### addListener('googleDocumentScannerModuleInstallProgress', ...)

```
addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when the Google Document Scanner module is installed.

Only available on Android.

| Param              | Type                                                               |
| ------------------ | ------------------------------------------------------------------ |
| **`eventName`**    | `'googleDocumentScannerModuleInstallProgress'`                     |
| **`listenerFunc`** | `(event: GoogleDocumentScannerModuleInstallProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.3.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on Android.

**Since:** 7.3.0

______________________________________________________________________

### Interfaces

#### ScanResult

Result of a document scan operation.

| Prop                | Type       | Description                                                                                                          | Since |
| ------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| **`scannedImages`** | `string[]` | An array of URIs for the scanned image pages (JPEG). Present if 'JPEG' or 'JPEG_PDF' was requested in resultFormats. | 7.3.0 |
| **`pdf`**           | `PdfInfo`  | Information about the generated PDF. Present if 'PDF' or 'JPEG_PDF' was requested in resultFormats.                  | 7.3.0 |

#### PdfInfo

| Prop            | Type     | Description                        | Since |
| --------------- | -------- | ---------------------------------- | ----- |
| **`uri`**       | `string` | The URI of the generated PDF file. | 7.3.0 |
| **`pageCount`** | `number` | The number of pages in the PDF.    | 7.3.0 |

#### ScanOptions

| Prop                       | Type      | Description                                        | Default              | Since                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | --------- | -------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`galleryImportAllowed`** | `boolean` | Whether to allow importing from the photo gallery. | `false`              | 7.3.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **`pageLimit`**            | `number`  | The maximum number of pages that can be scanned.   | `10`                 | 7.3.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **`resultFormats`**        | \`'JPEG'  | 'PDF'                                              | 'JPEG_PDF'\`         | The desired result formats. Can be 'JPEG', 'PDF', or 'JPEG_PDF'.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **`scannerMode`**          | \`'FULL'  | 'BASE'                                             | 'BASE_WITH_FILTER'\` | The scanner mode. BASE: Basic editing capabilities (crop, rotate, reorder pages, etc.). BASE_WITH_FILTER: Adds image filters (grayscale, auto image enhancement, etc.) to the BASE mode. FULL: Adds ML-enabled image cleaning capabilities (erase stains, fingers, etc.) to the BASE_WITH_FILTER mode. This mode will also allow future major features to be automatically added along with Google Play services updates, while the other two modes will maintain their current feature sets and only receive minor refinements. |

#### IsGoogleDocumentScannerModuleAvailableResult

| Prop            | Type      | Description                                                     | Since |
| --------------- | --------- | --------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not the Google Document Scanner module is available. | 7.3.0 |

#### PluginListenerHandle

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

#### GoogleDocumentScannerModuleInstallProgressEvent

| Prop           | Type                                      | Description                                                    | Since |
| -------------- | ----------------------------------------- | -------------------------------------------------------------- | ----- |
| **`state`**    | `GoogleDocumentScannerModuleInstallState` | The current state of the installation.                         | 7.3.0 |
| **`progress`** | `number`                                  | The progress of the installation in percent between 0 and 100. | 7.3.0 |

### Enums

#### GoogleDocumentScannerModuleInstallState

| Members               | Value | Since |
| --------------------- | ----- | ----- |
| **`UNKNOWN`**         | `0`   | 7.3.0 |
| **`PENDING`**         | `1`   | 7.3.0 |
| **`DOWNLOADING`**     | `2`   | 7.3.0 |
| **`CANCELED`**        | `3`   | 7.3.0 |
| **`COMPLETED`**       | `4`   | 7.3.0 |
| **`FAILED`**          | `5`   | 7.3.0 |
| **`INSTALLING`**      | `6`   | 7.3.0 |
| **`DOWNLOAD_PAUSED`** | `7`   | 7.3.0 |

## Notes

- The ML Kit Document Scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services. Users might have to wait for these to download before the first use. You can use the isGoogleDocumentScannerModuleAvailable and installGoogleDocumentScannerModule methods to check for and install the module, and listen to the googleDocumentScannerModuleInstallProgress event for progress updates.
- This API requires Android API level 21 or above.
- It also requires a minimal device total RAM of 1.7GB. If lower, it returns an `MlKitException` with error code `UNSUPPORTED` when calling the API (this plugin will reject the promise).
- Consider that generating document files takes time and requires processing power, so only request the output formats (JPEG, or PDF, or both) you actually need via the `resultFormats` option.

## FAQ

### Which platforms are supported by this plugin?

The plugin is only available on Android, since the underlying ML Kit Document Scanner is provided by Google Play services. All methods reject on other platforms.

### Why is the document scanner not available on first use?

The ML Kit Document Scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services, so users might have to wait for the download before the first use. Use `isGoogleDocumentScannerModuleAvailable()` to check for the module, `installGoogleDocumentScannerModule()` to install it, and listen to the `googleDocumentScannerModuleInstallProgress` event for progress updates.

### Which result formats can I get from a scan?

You can request JPEG images, a PDF file, or both via the `resultFormats` option. The result then contains an array of URIs for the scanned image pages and/or information about the generated PDF, including its URI and page count. Since generating document files takes time and processing power, only request the formats you actually need.

### What is the difference between the scanner modes?

The `BASE` mode provides basic editing capabilities such as crop, rotate, and reorder pages. The `BASE_WITH_FILTER` mode adds image filters such as grayscale and auto image enhancement. The `FULL` mode (the default) additionally provides ML-enabled image cleaning capabilities, for example erasing stains and fingers, and will automatically receive future major features along with Google Play services updates.

### Are there any device requirements?

Yes, the API requires Android API level 21 or above and a minimal device total RAM of 1.7 GB. On devices with less RAM, the API returns an `MlKitException` with error code `UNSUPPORTED` and the plugin rejects the promise.

### Can users import existing photos instead of scanning?

Yes, set the `galleryImportAllowed` option to `true` to allow importing pages from the photo gallery. It is disabled by default.

## Related Plugins

- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning.
- [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): Display PDF documents in a fullscreen native viewer.
- [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a scanned file with the default application.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Entity Extraction Plugin

Unofficial Capacitor plugin for [ML Kit Entity Extraction](https://developers.google.com/ml-kit/language/entity-extraction).[1](#fn:1)

> [!WARNING] The ML Kit Entity Extraction API is currently in **beta**. The API surface and behavior may change in a backwards-incompatible way in future releases.

## Use Cases

The Entity Extraction plugin detects structured data such as addresses, date-times, and phone numbers in raw text directly on the device, for example:

- **Messaging apps**: Turn detected phone numbers, addresses, or date-times into tappable actions.
- **Email clients**: Recognize tracking numbers, flight numbers, or IBANs and offer quick actions.
- **Calendar apps**: Suggest events from date-times mentioned in a message.
- **Finance apps**: Detect payment cards, IBANs, or money amounts in pasted text.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/entity-extraction` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/entity-extraction
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitEntityExtractionVersion` version of `com.google.mlkit:entity-extraction` (default: `16.0.0-beta6`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

Before you can extract entities, you must download the model for the language you want to use. The model is downloaded once and then reused for all subsequent extractions.

The following example shows how to download the English model and extract a date-time entity from a text. A `referenceTime` is provided so that relative date-times such as "tomorrow" can be resolved.

```
import {
  EntityExtraction,
  EntityType,
  ErrorCode,
  Language,
} from '@capacitor-mlkit/entity-extraction';

const downloadModel = async () => {
  await EntityExtraction.downloadModel({
    language: Language.English,
  });
};

const getDownloadedModels = async () => {
  const { languages } = await EntityExtraction.getDownloadedModels();
  return languages;
};

const extractEntities = async () => {
  try {
    const { annotations } = await EntityExtraction.extractEntities({
      text: 'Let\'s meet tomorrow at 5pm.',
      language: Language.English,
      referenceTime: Date.now(),
      referenceTimeZone: 'America/New_York',
    });
    for (const annotation of annotations) {
      for (const entity of annotation.entities) {
        if (entity.type === EntityType.DateTime) {
          console.log(annotation.text, entity.timestamp);
        }
      }
    }
  } catch (error) {
    if (error.code === ErrorCode.ModelNotDownloaded) {
      // The model must be downloaded first using `downloadModel(...)`.
    }
  }
};

const deleteDownloadedModel = async () => {
  await EntityExtraction.deleteDownloadedModel({
    language: Language.English,
  });
};
```

## API

- [`deleteDownloadedModel(...)`](#deletedownloadedmodel)
- [`downloadModel(...)`](#downloadmodel)
- [`extractEntities(...)`](#extractentities)
- [`getDownloadedModels()`](#getdownloadedmodels)
- [Interfaces](#interfaces)
- [Enums](#enums)

### deleteDownloadedModel(...)

```
deleteDownloadedModel(options: DeleteDownloadedModelOptions) => Promise<void>
```

Delete the model for the given language.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `DeleteDownloadedModelOptions` |

**Since:** 8.2.0

______________________________________________________________________

### downloadModel(...)

```
downloadModel(options: DownloadModelOptions) => Promise<void>
```

Download the model for the given language.

The model must be downloaded before entities can be extracted for a language.

Only available on Android and iOS.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `DownloadModelOptions` |

**Since:** 8.2.0

______________________________________________________________________

### extractEntities(...)

```
extractEntities(options: ExtractEntitiesOptions) => Promise<ExtractEntitiesResult>
```

Extract entities (e.g. addresses, date-times or phone numbers) from the given text.

The model for the given language must be downloaded first using the `downloadModel(...)` method. If the model is not downloaded, the method rejects with the `MODEL_NOT_DOWNLOADED` error code.

Only available on Android and iOS.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `ExtractEntitiesOptions` |

**Returns:** `Promise<ExtractEntitiesResult>`

**Since:** 8.2.0

______________________________________________________________________

### getDownloadedModels()

```
getDownloadedModels() => Promise<GetDownloadedModelsResult>
```

Get the languages for which a model has been downloaded.

Only available on Android and iOS.

**Returns:** `Promise<GetDownloadedModelsResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### DeleteDownloadedModelOptions

| Prop           | Type       | Description                                 | Since |
| -------------- | ---------- | ------------------------------------------- | ----- |
| **`language`** | `Language` | The language for which to delete the model. | 8.2.0 |

#### DownloadModelOptions

| Prop           | Type       | Description                                   | Since |
| -------------- | ---------- | --------------------------------------------- | ----- |
| **`language`** | `Language` | The language for which to download the model. | 8.2.0 |

#### ExtractEntitiesResult

| Prop              | Type                 | Description                | Since |
| ----------------- | -------------------- | -------------------------- | ----- |
| **`annotations`** | `EntityAnnotation[]` | The extracted annotations. | 8.2.0 |

#### EntityAnnotation

| Prop           | Type       | Description                                                               | Since |
| -------------- | ---------- | ------------------------------------------------------------------------- | ----- |
| **`text`**     | `string`   | The text segment within the original text that this annotation refers to. | 8.2.0 |
| **`start`**    | `number`   | The start index (inclusive) of the annotation in the original text.       | 8.2.0 |
| **`end`**      | `number`   | The end index (exclusive) of the annotation in the original text.         | 8.2.0 |
| **`entities`** | `Entity[]` | The entities that this annotation could refer to.                         | 8.2.0 |

#### Entity

| Prop                       | Type                    | Description                                                                                                   | Since |
| -------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | ----- |
| **`type`**                 | `EntityType`            | The type of the entity.                                                                                       | 8.2.0 |
| **`dateTimeGranularity`**  | `DateTimeGranularity`   | The granularity of the extracted date-time. Only available if `type` is `DATE_TIME`.                          | 8.2.0 |
| **`timestamp`**            | `number`                | The extracted date-time in milliseconds since epoch. Only available if `type` is `DATE_TIME`.                 | 8.2.0 |
| **`unnormalizedCurrency`** | `string`                | The currency of the money as it appears in the text (not canonicalized). Only available if `type` is `MONEY`. | 8.2.0 |
| **`integerPart`**          | `number`                | The integer part of the money amount. Only available if `type` is `MONEY`.                                    | 8.2.0 |
| **`fractionalPart`**       | `number`                | The fractional part of the money amount. Only available if `type` is `MONEY`.                                 | 8.2.0 |
| **`paymentCardNetwork`**   | `PaymentCardNetwork`    | The network of the payment card. Only available if `type` is `PAYMENT_CARD`.                                  | 8.2.0 |
| **`paymentCardNumber`**    | `string`                | The number of the payment card in canonical format. Only available if `type` is `PAYMENT_CARD`.               | 8.2.0 |
| **`airlineCode`**          | `string`                | The IATA airline designator (two or three letters). Only available if `type` is `FLIGHT_NUMBER`.              | 8.2.0 |
| **`flightNumber`**         | `string`                | The flight number (1 to 4 digits). Only available if `type` is `FLIGHT_NUMBER`.                               | 8.2.0 |
| **`isbn`**                 | `string`                | The full ISBN in canonical format. Only available if `type` is `ISBN`.                                        | 8.2.0 |
| **`iban`**                 | `string`                | The full IBAN in canonical format. Only available if `type` is `IBAN`.                                        | 8.2.0 |
| **`ibanCountryCode`**      | `string`                | The ISO 3166-1 alpha-2 country code of the IBAN. Only available if `type` is `IBAN`.                          | 8.2.0 |
| **`parcelCarrier`**        | `ParcelTrackingCarrier` | The parcel tracking carrier. Only available if `type` is `TRACKING_NUMBER`.                                   | 8.2.0 |
| **`parcelTrackingNumber`** | `string`                | The parcel tracking number in canonical format. Only available if `type` is `TRACKING_NUMBER`.                | 8.2.0 |

#### ExtractEntitiesOptions

| Prop                    | Type           | Description                                                                                                                           | Since |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**              | `string`       | The text to extract entities from.                                                                                                    | 8.2.0 |
| **`language`**          | `Language`     | The language of the model to use. The model for this language must be downloaded first using the `downloadModel(...)` method.         | 8.2.0 |
| **`referenceTime`**     | `number`       | The reference time (in milliseconds since epoch) used to resolve relative date-times (e.g. "tomorrow"). Defaults to the current time. | 8.2.0 |
| **`referenceTimeZone`** | `string`       | The reference time zone (as an IANA time zone identifier) used to resolve relative date-times. Defaults to the device's time zone.    | 8.2.0 |
| **`preferredLocale`**   | `string`       | The preferred locale (as a BCP-47 language tag) used to disambiguate entities. Defaults to the device's locale.                       | 8.2.0 |
| **`entityTypes`**       | `EntityType[]` | The entity types to extract. If not set, all entity types are extracted.                                                              | 8.2.0 |

#### GetDownloadedModelsResult

| Prop            | Type         | Description                                          | Since |
| --------------- | ------------ | ---------------------------------------------------- | ----- |
| **`languages`** | `Language[]` | The languages for which a model has been downloaded. | 8.2.0 |

### Enums

#### Language

| Members          | Value          | Since |
| ---------------- | -------------- | ----- |
| **`Arabic`**     | `'ARABIC'`     | 8.2.0 |
| **`Chinese`**    | `'CHINESE'`    | 8.2.0 |
| **`Dutch`**      | `'DUTCH'`      | 8.2.0 |
| **`English`**    | `'ENGLISH'`    | 8.2.0 |
| **`French`**     | `'FRENCH'`     | 8.2.0 |
| **`German`**     | `'GERMAN'`     | 8.2.0 |
| **`Italian`**    | `'ITALIAN'`    | 8.2.0 |
| **`Japanese`**   | `'JAPANESE'`   | 8.2.0 |
| **`Korean`**     | `'KOREAN'`     | 8.2.0 |
| **`Polish`**     | `'POLISH'`     | 8.2.0 |
| **`Portuguese`** | `'PORTUGUESE'` | 8.2.0 |
| **`Russian`**    | `'RUSSIAN'`    | 8.2.0 |
| **`Spanish`**    | `'SPANISH'`    | 8.2.0 |
| **`Thai`**       | `'THAI'`       | 8.2.0 |
| **`Turkish`**    | `'TURKISH'`    | 8.2.0 |

#### EntityType

| Members              | Value               | Description                                   | Since |
| -------------------- | ------------------- | --------------------------------------------- | ----- |
| **`Address`**        | `'ADDRESS'`         | A physical address.                           | 8.2.0 |
| **`DateTime`**       | `'DATE_TIME'`       | A date and time reference.                    | 8.2.0 |
| **`Email`**          | `'EMAIL'`           | An e-mail address.                            | 8.2.0 |
| **`FlightNumber`**   | `'FLIGHT_NUMBER'`   | A flight number in IATA format.               | 8.2.0 |
| **`Iban`**           | `'IBAN'`            | An International Bank Account Number (IBAN).  | 8.2.0 |
| **`Isbn`**           | `'ISBN'`            | An International Standard Book Number (ISBN). | 8.2.0 |
| **`Money`**          | `'MONEY'`           | An amount of money.                           | 8.2.0 |
| **`PaymentCard`**    | `'PAYMENT_CARD'`    | A payment card.                               | 8.2.0 |
| **`Phone`**          | `'PHONE'`           | A phone number.                               | 8.2.0 |
| **`TrackingNumber`** | `'TRACKING_NUMBER'` | A shipment tracking number.                   | 8.2.0 |
| **`Url`**            | `'URL'`             | A URL.                                        | 8.2.0 |

#### DateTimeGranularity

| Members       | Value       | Since |
| ------------- | ----------- | ----- |
| **`Unknown`** | `'UNKNOWN'` | 8.2.0 |
| **`Year`**    | `'YEAR'`    | 8.2.0 |
| **`Month`**   | `'MONTH'`   | 8.2.0 |
| **`Week`**    | `'WEEK'`    | 8.2.0 |
| **`Day`**     | `'DAY'`     | 8.2.0 |
| **`Hour`**    | `'HOUR'`    | 8.2.0 |
| **`Minute`**  | `'MINUTE'`  | 8.2.0 |
| **`Second`**  | `'SECOND'`  | 8.2.0 |

#### PaymentCardNetwork

| Members            | Value             | Since |
| ------------------ | ----------------- | ----- |
| **`Unknown`**      | `'UNKNOWN'`       | 8.2.0 |
| **`Amex`**         | `'AMEX'`          | 8.2.0 |
| **`DinersClub`**   | `'DINERS_CLUB'`   | 8.2.0 |
| **`Discover`**     | `'DISCOVER'`      | 8.2.0 |
| **`InterPayment`** | `'INTER_PAYMENT'` | 8.2.0 |
| **`Jcb`**          | `'JCB'`           | 8.2.0 |
| **`Maestro`**      | `'MAESTRO'`       | 8.2.0 |
| **`Mastercard`**   | `'MASTERCARD'`    | 8.2.0 |
| **`Mir`**          | `'MIR'`           | 8.2.0 |
| **`Troy`**         | `'TROY'`          | 8.2.0 |
| **`Unionpay`**     | `'UNIONPAY'`      | 8.2.0 |
| **`Visa`**         | `'VISA'`          | 8.2.0 |

#### ParcelTrackingCarrier

| Members          | Value           | Since |
| ---------------- | --------------- | ----- |
| **`Unknown`**    | `'UNKNOWN'`     | 8.2.0 |
| **`Fedex`**      | `'FEDEX'`       | 8.2.0 |
| **`Ups`**        | `'UPS'`         | 8.2.0 |
| **`Dhl`**        | `'DHL'`         | 8.2.0 |
| **`Usps`**       | `'USPS'`        | 8.2.0 |
| **`Ontrac`**     | `'ONTRAC'`      | 8.2.0 |
| **`Lasership`**  | `'LASERSHIP'`   | 8.2.0 |
| **`IsraelPost`** | `'ISRAEL_POST'` | 8.2.0 |
| **`SwissPost`**  | `'SWISS_POST'`  | 8.2.0 |
| **`Msc`**        | `'MSC'`         | 8.2.0 |
| **`Amazon`**     | `'AMAZON'`      | 8.2.0 |
| **`IParcel`**    | `'I_PARCEL'`    | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. All methods are only available on Android and iOS, so there is no web implementation.

### Which languages are supported?

The following languages are supported: Arabic, Chinese, Dutch, English, French, German, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Thai and Turkish (see the [`Language`](#language) enum). Note that a single model can extract entities from text in its language.

### Why does `extractEntities(...)` reject with `MODEL_NOT_DOWNLOADED`?

Entities can only be extracted for a language whose model has been downloaded. Download the model first using the `downloadModel(...)` method and handle the `MODEL_NOT_DOWNLOADED` error code to prompt a download.

### How do I resolve relative date-times such as "tomorrow"?

Provide a `referenceTime` (and optionally a `referenceTimeZone`) to the `extractEntities(...)` method. Relative date-times are resolved against this reference time. If not set, the current time and the device's time zone are used.

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Translate text before or after extracting entities.
- [Language Identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/): Detect the language of a text before choosing a model.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/entity-extraction/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/entity-extraction/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Face Detection Plugin

Unofficial Capacitor plugin for [ML Kit Face Detection](https://developers.google.com/ml-kit/vision/face-detection).[1](#fn:1)

## Use Cases

The Face Detection plugin is typically used whenever an app needs to locate faces in an image, for example:

- **Photo organization**: Detect which photos contain faces and where they are located, for example to crop thumbnails around them.
- **Selfie effects**: Use the detected face landmarks and contours to position stickers or other virtual elements on faces.
- **Smile detection**: Use the classification results to determine the probability that a person is smiling or has their eyes open.
- **Face tracking**: Maintain a consistent ID for each face across consecutive frames using the tracking option.

## 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     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/face-detection` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/face-detection
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### Dependencies

You need to add the following meta data **in** the `application` tag in your `AndroidManifest.xml`:

```
<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="face"/>
<!-- To use multiple models: android:value="face,model2,model3" -->
```

#### 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:

- `$mlkitFaceDetectionVersion` version of `com.google.mlkit:face-detection` (default: `16.1.7`)
- `$playServicesMlkitFaceDetectionVersion` version of `com.google.android.gms:play-services-mlkit-face-detection` (default: `17.1.0`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to detect faces in an image.

### Detect faces in an image

Detect human faces in an image at a local path. You can configure the accuracy/speed trade-off and enable landmarks, contours, classification (smiling and eyes open probabilities), and face tracking. Only available on Android and iOS:

```
import {
  FaceDetection,
  PerformanceMode,
  LandmarkMode,
  ContourMode,
  ClassificationMode,
} from '@capacitor-mlkit/face-detection';

const processImage = async () => {
  const { faces } = await FaceDetection.processImage({
    path: 'path/to/image.jpg',
    performanceMode: PerformanceMode.Fast,
    landmarkMode: LandmarkMode.All,
    contourMode: ContourMode.All,
    classificationMode: ClassificationMode.All,
    minFaceSize: 0.1,
    enableTracking: false,
  });
  return faces;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)
- [Enums](#enums)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Detects human faces from the supplied image.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 5.1.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop        | Type     | Description         | Since |
| ----------- | -------- | ------------------- | ----- |
| **`faces`** | `Face[]` | The detected faces. | 5.1.0 |

#### Face

Represents a face detected by `FaceDetector`.

| Prop                          | Type             | Description                                                                                                                                                                | Since |
| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bounds`**                  | `Rect`           | Returns the axis-aligned bounding rectangle of the detected face.                                                                                                          | 5.1.0 |
| **`landmarks`**               | `FaceLandmark[]` | Returns a list of face landmarks.                                                                                                                                          | 5.1.0 |
| **`contours`**                | `FaceContour[]`  | Returns a list of face contours.                                                                                                                                           | 5.1.0 |
| **`trackingId`**              | `number`         | Returns the tracking ID if the tracking is enabled.                                                                                                                        | 5.1.0 |
| **`headEulerAngleX`**         | `number`         | Returns the rotation of the face about the horizontal axis of the image. Positive euler X is the face is looking up.                                                       | 5.1.0 |
| **`headEulerAngleY`**         | `number`         | Returns the rotation of the face about the vertical axis of the image. Positive euler y is when the face turns toward the right side of the image that is being processed. | 5.1.0 |
| **`headEulerAngleZ`**         | `number`         | Returns the rotation of the face about the axis pointing out of the image. Positive euler z is a counter-clockwise rotation within the image plane.                        | 5.1.0 |
| **`smilingProbability`**      | `number`         | Returns a value between 0.0 and 1.0 giving a probability that the face is smiling.                                                                                         | 5.1.0 |
| **`leftEyeOpenProbability`**  | `number`         | Returns a value between 0.0 and 1.0 giving a probability that the face's left eye is open.                                                                                 | 5.1.0 |
| **`rightEyeOpenProbability`** | `number`         | Returns a value between 0.0 and 1.0 giving a probability that the face's right eye is open.                                                                                | 5.1.0 |

#### Rect

[Rect](#rect) holds four integer coordinates for a rectangle.

| Prop         | Type     | Description                                          | Since |
| ------------ | -------- | ---------------------------------------------------- | ----- |
| **`left`**   | `number` | The X coordinate of the left side of the rectangle.  | 5.1.0 |
| **`top`**    | `number` | The Y coordinate of the top of the rectangle.        | 5.1.0 |
| **`right`**  | `number` | The X coordinate of the right side of the rectangle. | 5.1.0 |
| **`bottom`** | `number` | The Y coordinate of the bottom of the rectangle.     | 5.1.0 |

#### FaceLandmark

Represent a face landmark. A landmark is a point on a detected face, such as an eye, nose, or mouth.

| Prop           | Type           | Description                                                                                | Since |
| -------------- | -------------- | ------------------------------------------------------------------------------------------ | ----- |
| **`type`**     | `LandmarkType` | Gets the [FaceLandmark](#facelandmark).[LandmarkType](#landmarktype) type.                 | 5.1.0 |
| **`position`** | `Point`        | Gets a 2D point for landmark position, where (0, 0) is the upper-left corner of the image. | 5.1.0 |

#### Point

[Point](#point) holds two coordinates

| Prop    | Type     |
| ------- | -------- |
| **`x`** | `number` |
| **`y`** | `number` |

#### FaceContour

Represent a face contour. A contour is a list of points on a detected face, such as the mouth.

| Prop         | Type          | Description                                                                                         | Since |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------- | ----- |
| **`type`**   | `ContourType` | Gets the [FaceContour](#facecontour).[ContourType](#contourtype) type.                              | 5.1.0 |
| **`points`** | `Point[]`     | Gets a list of 2D points for this face contour, where (0, 0) is the upper-left corner of the image. | 5.1.0 |

#### ProcessImageOptions

| Prop                     | Type                 | Description                                                                                                                                                                                     | Default                   | Since |
| ------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----- |
| **`path`**               | `string`             | The local path to the image file.                                                                                                                                                               |                           | 5.1.0 |
| **`performanceMode`**    | `PerformanceMode`    | Defines options to control accuracy / speed trade-offs in performing face detection.                                                                                                            | `PerformanceMode.Fast`    | 5.1.0 |
| **`landmarkMode`**       | `LandmarkMode`       | Defines options to enable face landmarks or not.                                                                                                                                                | `LandmarkMode.None`       | 5.1.0 |
| **`contourMode`**        | `ContourMode`        | Defines options to enable face contours or not.                                                                                                                                                 | `ContourMode.None`        | 5.1.0 |
| **`classificationMode`** | `ClassificationMode` | Defines options for characterizing attributes such as "smiling" * and "eyes open".                                                                                                              | `ClassificationMode.None` | 5.1.0 |
| **`minFaceSize`**        | `number`             | Sets the smallest desired face size, expressed as a proportion of the width of the head to the image width.                                                                                     | `0.1`                     | 5.1.0 |
| **`enableTracking`**     | `boolean`            | Enables face tracking, which will maintain a consistent ID for each face when processing consecutive frames. Tracking should be disabled for handling a series of non-consecutive still images. | `false`                   | 5.1.0 |

### Enums

#### LandmarkType

| Members           | Value | Description                                                                                                                                                                                                            | Since |
| ----------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`MouthBottom`** | `0`   | The center of the subject's bottom lip.                                                                                                                                                                                | 5.1.0 |
| **`LeftCheek`**   | `1`   | The midpoint between the subject's left mouth corner and the outer corner of the subject's left eye. For full profile faces, this becomes the centroid of the nose base, nose tip, left ear lobe and left ear tip.     | 5.1.0 |
| **`LeftEar`**     | `3`   | The midpoint of the subject's left ear tip and left ear lobe.                                                                                                                                                          | 5.1.0 |
| **`LeftEye`**     | `4`   | The center of the subject's left eye cavity.                                                                                                                                                                           | 5.1.0 |
| **`MouthLeft`**   | `5`   | The subject's left mouth corner where the lips meet.                                                                                                                                                                   | 5.1.0 |
| **`NoseBase`**    | `6`   | The midpoint between the subject's nostrils where the nose meets the face.                                                                                                                                             | 5.1.0 |
| **`RightCheek`**  | `7`   | The midpoint between the subject's right mouth corner and the outer corner of the subject's right eye. For full profile faces, this becomes the centroid of the nose base, nose tip, right ear lobe and right ear tip. | 5.1.0 |
| **`RightEar`**    | `9`   | The midpoint of the subject's right ear tip and right ear lobe.                                                                                                                                                        | 5.1.0 |
| **`RightEye`**    | `10`  | The center of the subject's right eye cavity.                                                                                                                                                                          | 5.1.0 |
| **`MouthRight`**  | `11`  | The subject's right mouth corner where the lips meet.                                                                                                                                                                  | 5.1.0 |

#### ContourType

| Members                  | Value | Description                                        | Since |
| ------------------------ | ----- | -------------------------------------------------- | ----- |
| **`Face`**               | `1`   | The outline of the subject's face.                 | 5.1.0 |
| **`LeftEyebrowTop`**     | `2`   | The top outline of the subject's left eyebrow.     | 5.1.0 |
| **`LeftEyebrowBottom`**  | `3`   | The bottom outline of the subject's left eyebrow.  | 5.1.0 |
| **`RightEyebrowTop`**    | `4`   | The top outline of the subject's right eyebrow.    | 5.1.0 |
| **`RightEyebrowBottom`** | `5`   | The bottom outline of the subject's right eyebrow. | 5.1.0 |
| **`LeftEye`**            | `6`   | The outline of the subject's left eye cavity.      | 5.1.0 |
| **`RightEye`**           | `7`   | The outline of the subject's right eye cavity.     | 5.1.0 |
| **`UpperLipTop`**        | `8`   | The top outline of the subject's upper lip.        | 5.1.0 |
| **`UpperLipBottom`**     | `9`   | The bottom outline of the subject's upper lip.     | 5.1.0 |
| **`LowerLipTop`**        | `10`  | The top outline of the subject's lower lip.        | 5.1.0 |
| **`LowerLipBottom`**     | `11`  | The bottom outline of the subject's lower lip.     | 5.1.0 |
| **`NoseBridge`**         | `12`  | The outline of the subject's nose bridge.          | 5.1.0 |
| **`NoseBottom`**         | `13`  | The outline of the subject's nose bridge.          | 5.1.0 |
| **`LeftCheek`**          | `14`  | The center of the left cheek.                      | 5.1.0 |
| **`RightCheek`**         | `15`  | The center of the right cheek.                     | 5.1.0 |

#### PerformanceMode

| Members        | Value | Description                                                                                                                                                                                                                 | Since |
| -------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Fast`**     | `1`   | Indicates a preference for speed in the options that may make an accuracy vs. speed trade-off. This will tend to detect fewer faces and may be less precise in determining values such as position, but will run faster.    | 5.1.0 |
| **`Accurate`** | `2`   | Indicates a preference for accuracy in the options that may make an accuracy vs. speed trade-off. This will tend to detect more faces and may be more precise in determining values such as position, at the cost of speed. | 5.1.0 |

#### LandmarkMode

| Members    | Value | Description                                             | Since |
| ---------- | ----- | ------------------------------------------------------- | ----- |
| **`None`** | `1`   | Does not perform landmark detection.                    | 5.1.0 |
| **`All`**  | `2`   | Detects [FaceLandmark](#facelandmark) for a given face. | 5.1.0 |

#### ContourMode

| Members    | Value | Description                                                                                                | Since |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- | ----- |
| **`None`** | `1`   | Does not perform contour detection.                                                                        | 5.1.0 |
| **`All`**  | `2`   | Detects [FaceContour](#facecontour) for a given face. Note that it would return contours for up to 5 faces | 5.1.0 |

#### ClassificationMode

| Members    | Value | Description                                        | Since |
| ---------- | ----- | -------------------------------------------------- | ----- |
| **`None`** | `1`   | Does not perform classification.                   | 5.1.0 |
| **`All`**  | `2`   | Performs "eyes open" and "smiling" classification. | 5.1.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android and iOS. The Web platform is not supported by the underlying ML Kit Face Detection SDK.

### Does the plugin recognize who is in the picture?

No, the plugin performs face detection, not face recognition. It detects the position of faces in an image along with attributes such as landmarks, contours, head rotation, and smiling probability, but it does not identify individuals. With the `enableTracking` option you can only maintain a consistent ID for the same face across consecutive frames.

### What is the difference between landmarks and contours?

A landmark is a single point on a detected face, such as an eye, nose, or mouth. A contour is a list of points that outlines a facial feature, such as the face oval, eyebrows, eyes, or lips. Landmarks are enabled via the `landmarkMode` option and contours via the `contourMode` option. Note that contours are only returned for up to 5 faces.

### How can I detect whether a person is smiling or has their eyes open?

Set the `classificationMode` option to `All`. The detected faces then contain the `smilingProbability`, `leftEyeOpenProbability`, and `rightEyeOpenProbability` properties, each a value between 0.0 and 1.0.

### What is the difference between this plugin and the Face Mesh Detection plugin?

This plugin detects faces with bounding boxes, landmarks, contours, and classifications on Android and iOS. The [ML Kit Face Mesh Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/) plugin returns a dense mesh of 468 3D points and triangle information for detected faces, but is only available on Android.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Face Mesh Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/): Detect face meshes with 468 3D points in images.
- [ML Kit Selfie Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/selfie-segmentation/): Segment selfies from the background with ML Kit Selfie Segmentation.
- [ML Kit Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/): Separate subjects from the background with ML Kit Subject Segmentation.
- [ML Kit Pose Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/pose-detection/): Detect body poses alongside faces in the same scene.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-detection/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-detection/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Face Mesh Detection Plugin

Unofficial Capacitor plugin for [ML Kit Face Mesh Detection](https://developers.google.com/ml-kit/vision/face-mesh-detection).[1](#fn:1)

## Use Cases

The Face Mesh Detection plugin is typically used whenever an app needs detailed facial geometry, for example:

- **Face filters and effects**: Use the 468 3D face mesh points and triangle surfaces to align virtual makeup, masks, or other effects with a face.
- **Facial feature analysis**: Work with the contours of the face oval, eyebrows, eyes, lips, and nose bridge.
- **Fast face localization**: Use the `BoundingBoxOnly` use case to quickly get the bounding boxes of detected faces.
- **Selfie tools**: Analyze up to 2 faces in detail using the full face mesh information.

## Compatibility

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

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/face-mesh-detection` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/face-mesh-detection
npx cap sync
```

### Android

#### 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:

- `$mlkitFaceMeshDetectionVersion` version of `com.google.mlkit:face-mesh-detection` (default: `16.0.0-beta1`)

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

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to detect face meshes in an image.

### Detect face meshes in an image

Detect face meshes in an image at a local path. Choose the `BoundingBoxOnly` use case for fast bounding box detection or the `FaceMesh` use case to also receive the 468 3D face mesh points and triangle information. Only available on Android:

```
import { FaceMeshDetection, UseCase } from '@capacitor-mlkit/face-mesh-detection';

const processImage = async () => {
  const { faceMeshs } = await FaceMeshDetection.processImage({
    path: 'path/to/image.jpg',
    useCase: UseCase.FaceMesh,
  });
  return faceMeshs;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)
- [Enums](#enums)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Detects face mesh from the supplied image.

Only available on Android.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 5.3.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop            | Type         | Description              | Since |
| --------------- | ------------ | ------------------------ | ----- |
| **`faceMeshs`** | `FaceMesh[]` | The detected face meshs. | 5.3.0 |

#### FaceMesh

Represents a face mesh detected by `FaceMeshDetector`.

When `BoundingBoxOnly` is selected, [`FaceMesh`](#facemesh) only contains valid bounding box.

When [`FaceMesh`](#facemesh) is selected, [`FaceMesh`](#facemesh) also contains a group of 468 3D face mesh points and related triangle information. Each point is represented by [`FaceMeshPoint`](#facemeshpoint) describing a specific position in detected face. The triangle information is a group of 3 `FaceMeshPoint`s representing a valid surface on Face (e.g. a valid small surface on nose tip).

| Prop                 | Type              | Description                                                                                                                                                                                                                                                                                                       | Since |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`bounds`**         | `Rect`            | Returns the axis-aligned bounding rectangle of the detected face mesh.                                                                                                                                                                                                                                            | 5.3.0 |
| **`contours`**       | `Contours`        | Returns contours with a list of [`FaceMeshPoint`](#facemeshpoint) representing the detected face.                                                                                                                                                                                                                 | 5.3.0 |
| **`faceMeshPoints`** | `FaceMeshPoint[]` | Returns a list of [`FaceMeshPoint`](#facemeshpoint) representing the whole detected face.                                                                                                                                                                                                                         | 5.3.0 |
| **`triangles`**      | `Triangle[]`      | Returns a list of [`Triangle`](#triangle) representing logical triangle surfaces of detected face. Each [`Triangle`](#triangle) contains 3 [`FaceMeshPoint`](#facemeshpoint), representing 3 points of the triangle surface. The sequence of the 3 points are constant and always counter clockwise in face mesh. | 5.3.0 |

#### Rect

[Rect](#rect) holds four integer coordinates for a rectangle.

| Prop         | Type     | Description                                          | Since |
| ------------ | -------- | ---------------------------------------------------- | ----- |
| **`left`**   | `number` | The X coordinate of the left side of the rectangle.  | 5.3.0 |
| **`top`**    | `number` | The Y coordinate of the top of the rectangle.        | 5.3.0 |
| **`right`**  | `number` | The X coordinate of the right side of the rectangle. | 5.3.0 |
| **`bottom`** | `number` | The Y coordinate of the bottom of the rectangle.     | 5.3.0 |

#### Contours

Represents contours with their face mesh points.

| Prop                     | Type              | Description                                              | Since |
| ------------------------ | ----------------- | -------------------------------------------------------- | ----- |
| **`faceOval`**           | `FaceMeshPoint[]` | Returns all points for the `FaceOval` contour.           | 5.3.0 |
| **`leftEyebrowTop`**     | `FaceMeshPoint[]` | Returns all points for the `LeftEyebrowTop` contour.     | 5.3.0 |
| **`leftEyebrowBottom`**  | `FaceMeshPoint[]` | Returns all points for the `LeftEyebrowBottom` contour.  | 5.3.0 |
| **`rightEyebrowTop`**    | `FaceMeshPoint[]` | Returns all points for the `RightEyebrowTop` contour.    | 5.3.0 |
| **`rightEyebrowBottom`** | `FaceMeshPoint[]` | Returns all points for the `RightEyebrowBottom` contour. | 5.3.0 |
| **`leftEye`**            | `FaceMeshPoint[]` | Returns all points for the `LeftEye` contour.            | 5.3.0 |
| **`rightEye`**           | `FaceMeshPoint[]` | Returns all points for the `RightEye` contour.           | 5.3.0 |
| **`upperLipTop`**        | `FaceMeshPoint[]` | Returns all points for the `UpperLipTop` contour.        | 5.3.0 |
| **`upperLipBottom`**     | `FaceMeshPoint[]` | Returns all points for the `UpperLipBottom` contour.     | 5.3.0 |
| **`lowerLipTop`**        | `FaceMeshPoint[]` | Returns all points for the `LowerLipTop` contour.        | 5.3.0 |
| **`lowerLipBottom`**     | `FaceMeshPoint[]` | Returns all points for the `LowerLipBottom` contour.     | 5.3.0 |
| **`noseBridge`**         | `FaceMeshPoint[]` | Returns all points for the `NoseBridge` contour.         | 5.3.0 |

#### FaceMeshPoint

Represents a 3D point in face mesh.

The index is an unique ID meaning a fixed position on face, ranging from 0 to 467.

In [`Point3D`](#point3d), `x` and `y` are pixel location of detected face in `InputImage`. `z` is also scaled to image size, while the origin will be somewhere in the center of all 468 face mesh points.

| Prop        | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Since |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`index`** | `number`  | Gets the index of the face mesh point, ranging from 0 to 467. For each specific point, the index is a constant value.                                                                                                                                                                                                                                                                                                                                                                            | 5.3.0 |
| **`point`** | `Point3D` | Gets a 3D point in face mesh. Inside [`Point3D`](#point3d), `X` and `Y` means a 2D position in original image. More information on the `Z` value: - The unit of measure for the `Z` value is the same as `X` and `Y`. - The smaller the `Z` value, the closer that landmark is to the camera. - The `Z` origin is approximately at the center of all 468 face mesh points. `Z` value will be negative if the point is close to camera and will be positive if the point is away from the camera. | 5.3.0 |

#### Point3D

Represents a 3D point.

| Prop    | Type     | Description                       | Since |
| ------- | -------- | --------------------------------- | ----- |
| **`x`** | `number` | Returns the X value of the point. | 5.3.0 |
| **`y`** | `number` | Returns the Y value of the point. | 5.3.0 |
| **`z`** | `number` | Returns the Z value of the point. | 5.3.0 |

#### Triangle

Represents a triangle with 3 generic points.

| Prop         | Type              | Description                                            | Since |
| ------------ | ----------------- | ------------------------------------------------------ | ----- |
| **`points`** | `FaceMeshPoint[]` | Returns all points inside the [`Triangle`](#triangle). | 5.3.0 |

#### ProcessImageOptions

| Prop          | Type      | Description                                                                                                                                                                                                                                                                                                                                                                              | Default            | Since |
| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| **`path`**    | `string`  | The local path to the image file.                                                                                                                                                                                                                                                                                                                                                        |                    | 5.3.0 |
| **`useCase`** | `UseCase` | Sets the use case. When `BoundingBoxOnly` is selected, the returned [`FaceMesh`](#facemesh) only contains bounding box. When [`FaceMesh`](#facemesh) is selected, the returned [`FaceMesh`](#facemesh) contains bounding box as well as 468 [`FaceMeshPoint`](#facemeshpoint) and triangle information. It detects at most 2 faces in this case and it is slower than `BoundingBoxOnly`. | `UseCase.FaceMesh` | 5.3.0 |

### Enums

#### UseCase

| Members               | Value | Description                                                                           | Since |
| --------------------- | ----- | ------------------------------------------------------------------------------------- | ----- |
| **`BoundingBoxOnly`** | `0`   | Return bounding box for detected face.                                                | 5.3.0 |
| **`FaceMesh`**        | `1`   | Return face mesh info for detected face. It detects at most 2 faces in this use case. | 5.3.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android. iOS and Web are not supported by the underlying ML Kit Face Mesh Detection SDK.

### What is the difference between the `BoundingBoxOnly` and `FaceMesh` use cases?

With `BoundingBoxOnly`, the result only contains a valid bounding box for each detected face, which is faster. With `FaceMesh` (the default), the result additionally contains a group of 468 3D face mesh points, contours, and triangle information, but it detects at most 2 faces and is slower.

### What exactly is a face mesh point?

A face mesh point is a 3D point on a detected face with an index between 0 and 467, where each index always refers to the same fixed position on the face. The `x` and `y` values are pixel locations in the input image, while the `z` value describes the distance to the camera: the smaller the value, the closer that point is to the camera.

### What is the difference between this plugin and the Face Detection plugin?

The [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/) plugin detects faces with bounding boxes, landmarks, contours, and classifications such as smiling probability, and works on Android and iOS. This plugin returns a much denser mesh of 468 3D points and triangle information for detailed facial geometry, but is only available on Android.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Detect faces with landmarks, contours, and classifications in images.
- [ML Kit Selfie Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/selfie-segmentation/): Segment selfies from the background with ML Kit Selfie Segmentation.
- [ML Kit Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/): Separate subjects from the background with ML Kit Subject Segmentation.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-mesh-detection/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-mesh-detection/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Image Description Plugin

Unofficial Capacitor plugin for [ML Kit GenAI Image Description](https://developers.google.com/ml-kit/genai/image-description).[1](#fn:1)

> [!WARNING] The ML Kit GenAI APIs are currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The GenAI Image Description plugin is typically used to generate a natural-language description of an image on-device using Gemini Nano, for example:

- **Accessibility**: Generate alternative text for images to support screen readers.
- **Content moderation**: Get a textual summary of user-uploaded images.
- **Search and organization**: Describe images to make them searchable or to auto-tag a photo library.

## Requirements

This plugin uses [Gemini Nano](https://developers.google.com/ml-kit/genai), which runs entirely on-device. It is only available on Android and has the following device requirements:

- The device must support Gemini Nano (see [supported devices](https://developers.google.com/ml-kit/genai#supported_devices)).
- The device must run Android API level 26 or higher.
- The device must not have an unlocked bootloader.

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-image-description` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-image-description
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiImageDescriptionVersion` version of `com.google.mlkit:genai-image-description` (default: `1.0.0-beta1`)

## Usage

The following example shows how to check the feature status, download the feature and describe an image.

> The image description is currently only available in English.

### Check the feature status

Before using the image description feature, check whether it is available on the device:

```
import {
  FeatureStatus,
  GenAiImageDescription,
} from '@capacitor-mlkit/genai-image-description';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiImageDescription.checkFeatureStatus();
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiImageDescription } from '@capacitor-mlkit/genai-image-description';

const downloadFeature = async () => {
  await GenAiImageDescription.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiImageDescription.downloadFeature();
};
```

### Describe an image

Pass the local file path of the image to `describeImage(...)` to generate a description. Add a listener for the `inferenceProgress` event to receive partial results as they are generated:

```
import { GenAiImageDescription } from '@capacitor-mlkit/genai-image-description';

const describeImage = async () => {
  await GenAiImageDescription.addListener('inferenceProgress', event => {
    console.log('Partial result:', event.text);
  });
  const { description } = await GenAiImageDescription.describeImage({
    path: 'file:///path/to/image.jpg',
  });
  return description;
};
```

## API

- [`checkFeatureStatus()`](#checkfeaturestatus)
- [`describeImage(...)`](#describeimage)
- [`downloadFeature()`](#downloadfeature)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('inferenceProgress', ...)`](#addlistenerinferenceprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### checkFeatureStatus()

```
checkFeatureStatus() => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the image description feature.

If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### describeImage(...)

```
describeImage(options: DescribeImageOptions) => Promise<DescribeImageResult>
```

Generate a natural-language description of the given image.

The `inferenceProgress` event listener will notify you about partial results as they are generated. The returned promise resolves with the full result.

The description is currently only available in English.

Only available on Android.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `DescribeImageOptions` |

**Returns:** `Promise<DescribeImageResult>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature()

```
downloadFeature() => Promise<void>
```

Download the image description feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the image description feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('inferenceProgress', ...)

```
addListener(eventName: 'inferenceProgress', listenerFunc: (event: InferenceProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new partial result is available during inference.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'inferenceProgress'`                     |
| **`listenerFunc`** | `(event: InferenceProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                                       | Since |
| ------------------- | --------------- | ----------------------------------------------------------------- | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the image description feature. | 8.2.0 |

#### DescribeImageResult

| Prop              | Type     | Description                                    | Since |
| ----------------- | -------- | ---------------------------------------------- | ----- |
| **`description`** | `string` | The natural-language description of the image. | 8.2.0 |

#### DescribeImageOptions

| Prop       | Type     | Description                                   | Since |
| ---------- | -------- | --------------------------------------------- | ----- |
| **`path`** | `string` | The local file path of the image to describe. | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### InferenceProgressEvent

| Prop       | Type     | Description                         | Since |
| ---------- | -------- | ----------------------------------- | ----- |
| **`text`** | `string` | The new text of the partial result. | 8.2.0 |

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The image description is performed on-device by Gemini Nano. This requires a device that supports Gemini Nano, Android API level 26 or higher and a locked bootloader (see [Requirements](#requirements)). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are based on Gemini Nano and AICore, which are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### In which language is the description generated?

The image description is currently only available in English. Support for more languages is planned for future releases.

### How do I get the description as a stream?

Add a listener for the `inferenceProgress` event before calling `describeImage(...)`. The listener is called with each partial result as it is generated. The promise returned by `describeImage(...)` resolves with the full result.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Unofficial Capacitor plugin for ML Kit Translation.
- [Smart Reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/): Unofficial Capacitor plugin for ML Kit Smart Reply.
- [GenAI Prompt](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-prompt/): Run custom GenAI prompts, for example to expand on a generated image description.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-image-description/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-image-description/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Prompt Plugin

Unofficial Capacitor plugin for the [ML Kit GenAI Prompt API](https://developers.google.com/ml-kit/genai/prompt).[1](#fn:1)

> [!WARNING] The ML Kit GenAI APIs are currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The GenAI Prompt plugin is typically used to send custom natural-language requests to Gemini Nano on-device, for example:

- **Content generation**: Generate short texts such as poems, captions or replies from a custom prompt.
- **Text transformation**: Rephrase, classify or extract information from user-provided text.
- **Image understanding**: Ask questions about an image by combining an image with a text prompt.

## Requirements

This plugin uses [Gemini Nano](https://developers.google.com/ml-kit/genai), which runs entirely on-device. It is only available on Android and has the following device requirements:

- The device must support Gemini Nano (see [supported devices](https://developers.google.com/ml-kit/genai#supported_devices)).
- The device must run Android API level 26 or higher.
- The device must not have an unlocked bootloader.

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

> [!IMPORTANT] The Prompt API performs open-ended generation with an on-device model. The output is **not moderated**. You are responsible for reviewing the model output for your use case (see [Responsible AI](https://developers.google.com/ml-kit/genai/prompt#responsible_ai)).

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-prompt` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-prompt
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiPromptVersion` version of `com.google.mlkit:genai-prompt` (default: `1.0.0-beta2`)

## Usage

The following example shows how to check the feature status, download the feature and generate content from a prompt.

> The prompt must be under 4,000 tokens (or about 3,000 English words). Use cases that require a long output (more than 256 tokens) should be avoided. The Prompt API is currently only validated for English and Korean.

### Check the feature status

Before using the prompt feature, check whether it is available on the device:

```
import { FeatureStatus, GenAiPrompt } from '@capacitor-mlkit/genai-prompt';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiPrompt.checkFeatureStatus();
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiPrompt } from '@capacitor-mlkit/genai-prompt';

const downloadFeature = async () => {
  await GenAiPrompt.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiPrompt.downloadFeature();
};
```

### Generate content

Pass a prompt to `generateContent(...)` to generate content. Add a listener for the `inferenceProgress` event to receive partial results as they are generated:

```
import { GenAiPrompt } from '@capacitor-mlkit/genai-prompt';

const generateContent = async () => {
  await GenAiPrompt.addListener('inferenceProgress', event => {
    console.log('Partial result:', event.text);
  });
  const { text } = await GenAiPrompt.generateContent({
    prompt: 'Write a short poem about the sea.',
  });
  return text;
};
```

You can also include an image in the prompt for a multimodal (image and text) request and tune the generation with optional parameters:

```
import { GenAiPrompt } from '@capacitor-mlkit/genai-prompt';

const generateContentFromImage = async () => {
  const { text } = await GenAiPrompt.generateContent({
    prompt: 'What is shown in this image?',
    imagePath: 'file:///path/to/image.jpg',
    temperature: 0.2,
    topK: 16,
    maxOutputTokens: 256,
  });
  return text;
};
```

## API

- [`checkFeatureStatus()`](#checkfeaturestatus)
- [`downloadFeature()`](#downloadfeature)
- [`generateContent(...)`](#generatecontent)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('inferenceProgress', ...)`](#addlistenerinferenceprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### checkFeatureStatus()

```
checkFeatureStatus() => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the prompt feature.

If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature()

```
downloadFeature() => Promise<void>
```

Download the prompt feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

**Since:** 8.2.0

______________________________________________________________________

### generateContent(...)

```
generateContent(options: GenerateContentOptions) => Promise<GenerateContentResult>
```

Generate content from a custom text-only or multimodal (image and text) prompt.

The `inferenceProgress` event listener will notify you about partial results as they are generated. The returned promise resolves with the full result.

The output is open-ended generation from an on-device model and is not moderated. The prompt is currently only validated for English and Korean.

Only available on Android.

| Param         | Type                     |
| ------------- | ------------------------ |
| **`options`** | `GenerateContentOptions` |

**Returns:** `Promise<GenerateContentResult>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the prompt feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('inferenceProgress', ...)

```
addListener(eventName: 'inferenceProgress', listenerFunc: (event: InferenceProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new partial result is available during inference.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'inferenceProgress'`                     |
| **`listenerFunc`** | `(event: InferenceProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                            | Since |
| ------------------- | --------------- | ------------------------------------------------------ | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the prompt feature. | 8.2.0 |

#### GenerateContentResult

| Prop       | Type     | Description         | Since |
| ---------- | -------- | ------------------- | ----- |
| **`text`** | `string` | The generated text. | 8.2.0 |

#### GenerateContentOptions

| Prop                  | Type     | Description                                                                                                                                                                                            | Since |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`imagePath`**       | `string` | The local file path of an image to include in the prompt for a multimodal (image and text) request.                                                                                                    | 8.2.0 |
| **`maxOutputTokens`** | `number` | The maximum number of tokens that can be generated in the response. Use cases that require a long output (more than 256 tokens) should be avoided. If not set, the default value of the model is used. | 8.2.0 |
| **`prompt`**          | `string` | The prompt to generate content from. The input must be under 4,000 tokens (or about 3,000 English words).                                                                                              | 8.2.0 |
| **`seed`**            | `number` | The random seed used during inference. Using the same seed with the same options produces deterministic results. If not set, the default value of the model is used.                                   | 8.2.0 |
| **`temperature`**     | `number` | Controls the randomness of the output. Lower values produce more deterministic output, higher values produce more creative output. If not set, the default value of the model is used.                 | 8.2.0 |
| **`topK`**            | `number` | The number of highest-probability tokens that are considered when sampling the next token. If not set, the default value of the model is used.                                                         | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### InferenceProgressEvent

| Prop       | Type     | Description                         | Since |
| ---------- | -------- | ----------------------------------- | ----- |
| **`text`** | `string` | The new text of the partial result. | 8.2.0 |

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The content generation is performed on-device by Gemini Nano. This requires a device that supports Gemini Nano, Android API level 26 or higher and a locked bootloader (see [Requirements](#requirements)). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are based on Gemini Nano and AICore, which are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### How large can the prompt be?

The prompt must be under 4,000 tokens (or about 3,000 English words). Use cases that require a long output (more than 256 tokens) should be avoided.

### Is the output moderated?

No, the Prompt API performs open-ended generation with an on-device model and the output is not moderated. You are responsible for reviewing the model output for your use case.

### How do I get the output as a stream?

Add a listener for the `inferenceProgress` event before calling `generateContent(...)`. The listener is called with each partial result as it is generated. The promise returned by `generateContent(...)` resolves with the full result.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [GenAI Image Description](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-image-description/): Unofficial Capacitor plugin for ML Kit GenAI Image Description.
- [GenAI Summarization](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-summarization/): Unofficial Capacitor plugin for ML Kit GenAI Summarization.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-prompt/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-prompt/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Proofreading Plugin

Unofficial Capacitor plugin for [ML Kit GenAI Proofreading](https://developers.google.com/ml-kit/genai/proofreading).[1](#fn:1)

> [!WARNING] The ML Kit GenAI APIs are currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The GenAI Proofreading plugin is typically used to refine grammar and fix spelling in short content on-device using Gemini Nano, for example:

- **Message polishing**: Correct typos and grammar in chat or email drafts before sending.
- **Form input cleanup**: Proofread user-generated text such as reviews or comments.
- **Voice-to-text refinement**: Clean up text produced by voice dictation.

## Requirements

This plugin uses [Gemini Nano](https://developers.google.com/ml-kit/genai), which runs entirely on-device. It is only available on Android and has the following device requirements:

- The device must support Gemini Nano (see [supported devices](https://developers.google.com/ml-kit/genai#supported_devices)).
- The device must run Android API level 26 or higher.
- The device must not have an unlocked bootloader.

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-proofreading` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-proofreading
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiProofreadingVersion` version of `com.google.mlkit:genai-proofreading` (default: `1.0.0-beta1`)

## Usage

The following example shows how to check the feature status, download the feature and proofread a text.

### Check the feature status

Before using the proofreading feature, check whether it is available on the device. The feature availability depends on the configured input type and language:

```
import {
  FeatureStatus,
  GenAiProofreading,
  InputType,
  Language,
} from '@capacitor-mlkit/genai-proofreading';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiProofreading.checkFeatureStatus({
    inputType: InputType.Keyboard,
    language: Language.English,
  });
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiProofreading, InputType, Language } from '@capacitor-mlkit/genai-proofreading';

const downloadFeature = async () => {
  await GenAiProofreading.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiProofreading.downloadFeature({
    inputType: InputType.Keyboard,
    language: Language.English,
  });
};
```

### Proofread a text

Pass the text to `proofread(...)` to generate corrected suggestions. Add a listener for the `inferenceProgress` event to receive partial results as they are generated:

```
import { GenAiProofreading, InputType, Language } from '@capacitor-mlkit/genai-proofreading';

const proofread = async () => {
  await GenAiProofreading.addListener('inferenceProgress', event => {
    console.log('Partial result:', event.text);
  });
  const { results } = await GenAiProofreading.proofread({
    text: 'Capacitor is an open source natvie runtime for buildng Web Native apps.',
    inputType: InputType.Keyboard,
    language: Language.English,
  });
  return results;
};
```

## API

- [`checkFeatureStatus(...)`](#checkfeaturestatus)
- [`downloadFeature(...)`](#downloadfeature)
- [`proofread(...)`](#proofread)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('inferenceProgress', ...)`](#addlistenerinferenceprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### checkFeatureStatus(...)

```
checkFeatureStatus(options?: FeatureOptions | undefined) => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the proofreading feature.

If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature(...)

```
downloadFeature(options?: FeatureOptions | undefined) => Promise<void>
```

Download the proofreading feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Since:** 8.2.0

______________________________________________________________________

### proofread(...)

```
proofread(options: ProofreadOptions) => Promise<ProofreadResult>
```

Proofread the given text.

The `inferenceProgress` event listener will notify you about partial results as they are generated. The returned promise resolves with the full result.

Only available on Android.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `ProofreadOptions` |

**Returns:** `Promise<ProofreadResult>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the proofreading feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('inferenceProgress', ...)

```
addListener(eventName: 'inferenceProgress', listenerFunc: (event: InferenceProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new partial result is available during inference.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'inferenceProgress'`                     |
| **`listenerFunc`** | `(event: InferenceProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                                  | Since |
| ------------------- | --------------- | ------------------------------------------------------------ | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the proofreading feature. | 8.2.0 |

#### FeatureOptions

The feature availability depends on the configured input type and language. Therefore, `checkFeatureStatus(...)` and `downloadFeature(...)` take the same base options as `proofread(...)`.

| Prop            | Type        | Description                     | Default              | Since |
| --------------- | ----------- | ------------------------------- | -------------------- | ----- |
| **`inputType`** | `InputType` | The type of the input text.     | `InputType.Keyboard` | 8.2.0 |
| **`language`**  | `Language`  | The language of the input text. | `Language.English`   | 8.2.0 |

#### ProofreadResult

| Prop          | Type       | Description                                                                                                                                                                  | Since |
| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`results`** | `string[]` | The proofread suggestions for the input text. More than one result may be returned. If multiple suggestions are returned, they are sorted in descending order of confidence. | 8.2.0 |

#### ProofreadOptions

| Prop       | Type     | Description            | Since |
| ---------- | -------- | ---------------------- | ----- |
| **`text`** | `string` | The text to proofread. | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### InferenceProgressEvent

| Prop       | Type     | Description                         | Since |
| ---------- | -------- | ----------------------------------- | ----- |
| **`text`** | `string` | The new text of the partial result. | 8.2.0 |

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

#### InputType

| Members        | Value        | Description                                              | Since |
| -------------- | ------------ | -------------------------------------------------------- | ----- |
| **`Keyboard`** | `'KEYBOARD'` | The input text was typed on a keyboard.                  | 8.2.0 |
| **`Voice`**    | `'VOICE'`    | The input text was produced by converting voice to text. | 8.2.0 |

#### Language

| Members        | Value        | Since |
| -------------- | ------------ | ----- |
| **`English`**  | `'ENGLISH'`  | 8.2.0 |
| **`French`**   | `'FRENCH'`   | 8.2.0 |
| **`German`**   | `'GERMAN'`   | 8.2.0 |
| **`Italian`**  | `'ITALIAN'`  | 8.2.0 |
| **`Japanese`** | `'JAPANESE'` | 8.2.0 |
| **`Korean`**   | `'KOREAN'`   | 8.2.0 |
| **`Spanish`**  | `'SPANISH'`  | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The proofreading is performed on-device by Gemini Nano. This requires a device that supports Gemini Nano, Android API level 26 or higher and a locked bootloader (see [Requirements](#requirements)). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are based on Gemini Nano and AICore, which are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### Which languages are supported?

Proofreading is supported for English, French, German, Italian, Japanese, Korean and Spanish. Use the `Language` enum to configure the language of the input text.

### How do I get the result as a stream?

Add a listener for the `inferenceProgress` event before calling `proofread(...)`. The listener is called with each partial result as it is generated. The promise returned by `proofread(...)` resolves with the full result.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [GenAI Summarization](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-summarization/): Unofficial Capacitor plugin for ML Kit GenAI Summarization.
- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Unofficial Capacitor plugin for ML Kit Translation.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-proofreading/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-proofreading/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Rewriting Plugin

Unofficial Capacitor plugin for [ML Kit GenAI Rewriting](https://developers.google.com/ml-kit/genai/rewriting).[1](#fn:1)

> [!WARNING] The ML Kit GenAI APIs are currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The GenAI Rewriting plugin is typically used to reword short messages in different tones and styles on-device using Gemini Nano, for example:

- **Tone adjustments**: Rewrite a message to sound more friendly or more professional before sending it.
- **Length adjustments**: Shorten or elaborate a draft to fit the situation.
- **Expressive messaging**: Add emojis or rephrase text to give it a fresh look.

## Requirements

This plugin uses [Gemini Nano](https://developers.google.com/ml-kit/genai), which runs entirely on-device. It is only available on Android and has the following device requirements:

- The device must support Gemini Nano (see [supported devices](https://developers.google.com/ml-kit/genai#supported_devices)).
- The device must run Android API level 26 or higher.
- The device must not have an unlocked bootloader.

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-rewriting` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-rewriting
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiRewritingVersion` version of `com.google.mlkit:genai-rewriting` (default: `1.0.0-beta1`)

## Usage

The following example shows how to check the feature status, download the feature and rewrite a text.

### Check the feature status

Before using the rewriting feature, check whether it is available on the device. The feature availability depends on the configured output type and language:

```
import {
  FeatureStatus,
  GenAiRewriting,
  Language,
  OutputType,
} from '@capacitor-mlkit/genai-rewriting';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiRewriting.checkFeatureStatus({
    language: Language.English,
    outputType: OutputType.Elaborate,
  });
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiRewriting, Language, OutputType } from '@capacitor-mlkit/genai-rewriting';

const downloadFeature = async () => {
  await GenAiRewriting.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiRewriting.downloadFeature({
    language: Language.English,
    outputType: OutputType.Elaborate,
  });
};
```

### Rewrite a text

Pass the text to `rewrite(...)` to generate the rewritten suggestions. Add a listener for the `inferenceProgress` event to receive partial results as they are generated:

```
import { GenAiRewriting, Language, OutputType } from '@capacitor-mlkit/genai-rewriting';

const rewrite = async () => {
  await GenAiRewriting.addListener('inferenceProgress', event => {
    console.log('Partial result:', event.text);
  });
  const { results } = await GenAiRewriting.rewrite({
    text: 'Capacitor is an open source native runtime for building Web Native apps.',
    language: Language.English,
    outputType: OutputType.Elaborate,
  });
  return results;
};
```

## API

- [`checkFeatureStatus(...)`](#checkfeaturestatus)
- [`downloadFeature(...)`](#downloadfeature)
- [`rewrite(...)`](#rewrite)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('inferenceProgress', ...)`](#addlistenerinferenceprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### checkFeatureStatus(...)

```
checkFeatureStatus(options?: FeatureOptions | undefined) => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the rewriting feature.

If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature(...)

```
downloadFeature(options?: FeatureOptions | undefined) => Promise<void>
```

Download the rewriting feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Since:** 8.2.0

______________________________________________________________________

### rewrite(...)

```
rewrite(options: RewriteOptions) => Promise<RewriteResult>
```

Rewrite the given text in the configured style.

The `inferenceProgress` event listener will notify you about partial results as they are generated. The returned promise resolves with the full result.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `RewriteOptions` |

**Returns:** `Promise<RewriteResult>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the rewriting feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('inferenceProgress', ...)

```
addListener(eventName: 'inferenceProgress', listenerFunc: (event: InferenceProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new partial result is available during inference.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'inferenceProgress'`                     |
| **`listenerFunc`** | `(event: InferenceProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                               | Since |
| ------------------- | --------------- | --------------------------------------------------------- | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the rewriting feature. | 8.2.0 |

#### FeatureOptions

The feature availability depends on the configured output type and language. Therefore, `checkFeatureStatus(...)` and `downloadFeature(...)` take the same base options as `rewrite(...)`.

| Prop             | Type         | Description                                            | Default                | Since |
| ---------------- | ------------ | ------------------------------------------------------ | ---------------------- | ----- |
| **`language`**   | `Language`   | The language of the input text.                        | `Language.English`     | 8.2.0 |
| **`outputType`** | `OutputType` | The style in which the input text should be rewritten. | `OutputType.Elaborate` | 8.2.0 |

#### RewriteResult

| Prop          | Type       | Description                                                               | Since |
| ------------- | ---------- | ------------------------------------------------------------------------- | ----- |
| **`results`** | `string[]` | The rewritten text suggestions, sorted in descending order of confidence. | 8.2.0 |

#### RewriteOptions

| Prop       | Type     | Description                                              | Since |
| ---------- | -------- | -------------------------------------------------------- | ----- |
| **`text`** | `string` | The text to rewrite. The input must be under 256 tokens. | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### InferenceProgressEvent

| Prop       | Type     | Description                         | Since |
| ---------- | -------- | ----------------------------------- | ----- |
| **`text`** | `string` | The new text of the partial result. | 8.2.0 |

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

#### Language

| Members        | Value        | Since |
| -------------- | ------------ | ----- |
| **`English`**  | `'ENGLISH'`  | 8.2.0 |
| **`French`**   | `'FRENCH'`   | 8.2.0 |
| **`German`**   | `'GERMAN'`   | 8.2.0 |
| **`Italian`**  | `'ITALIAN'`  | 8.2.0 |
| **`Japanese`** | `'JAPANESE'` | 8.2.0 |
| **`Korean`**   | `'KOREAN'`   | 8.2.0 |
| **`Spanish`**  | `'SPANISH'`  | 8.2.0 |

#### OutputType

| Members            | Value            | Description                                    | Since |
| ------------------ | ---------------- | ---------------------------------------------- | ----- |
| **`Elaborate`**    | `'ELABORATE'`    | Elaborate the input text.                      | 8.2.0 |
| **`Emojify`**      | `'EMOJIFY'`      | Insert appropriate emojis into the input text. | 8.2.0 |
| **`Shorten`**      | `'SHORTEN'`      | Shorten the input text.                        | 8.2.0 |
| **`Friendly`**     | `'FRIENDLY'`     | Make the input text more friendly.             | 8.2.0 |
| **`Professional`** | `'PROFESSIONAL'` | Make the input text more professional.         | 8.2.0 |
| **`Rephrase`**     | `'REPHRASE'`     | Rephrase the input text.                       | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The rewriting is performed on-device by Gemini Nano. This requires a device that supports Gemini Nano, Android API level 26 or higher and a locked bootloader (see [Requirements](#requirements)). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are based on Gemini Nano and AICore, which are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### How large can the input text be?

The input must be under 256 tokens.

### Why does `rewrite(...)` return multiple results?

The model may return more than one suggestion. The suggestions are sorted in descending order of confidence, so the first result is the most confident one.

### How do I get the rewritten text as a stream?

Add a listener for the `inferenceProgress` event before calling `rewrite(...)`. The listener is called with each partial result as it is generated. The promise returned by `rewrite(...)` resolves with the full result.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Unofficial Capacitor plugin for ML Kit Translation.
- [Smart Reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/): Unofficial Capacitor plugin for ML Kit Smart Reply.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-rewriting/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-rewriting/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Speech Recognition Plugin

Unofficial Capacitor plugin for [ML Kit GenAI Speech Recognition](https://developers.google.com/ml-kit/genai/speech-recognition).[1](#fn:1)

> [!WARNING] The ML Kit GenAI Speech Recognition API is currently in **alpha**. The API surface and behavior may change in future releases and breaking changes are expected. Additionally, the advanced recognition mode is currently only available on a very limited set of devices (e.g. Pixel 10).

## Use Cases

The GenAI Speech Recognition plugin is typically used to transcribe spoken words into text in real time, for example:

- **Voice input**: Let users dictate messages, notes or search queries instead of typing.
- **Live transcription**: Transcribe meetings, lectures or interviews on-device.
- **Voice commands**: Build hands-free experiences that react to spoken input.

## Requirements

This plugin performs speech recognition entirely on-device. It is only available on Android and supports two recognition modes with different requirements:

- **Basic mode**: Speech recognition using a traditional speech model. Requires Android API level 31 or higher. Supported locales: `en-US`, `fr-FR` (beta), `it-IT` (beta), `de-DE` (beta), `es-ES` (beta), `hi-IN` (beta), `ja-JP` (beta), `pt-BR` (beta), `tr-TR` (beta), `pl-PL` (beta), `cmn-Hans-CN` (beta), `ko-KR` (beta), `cmn-Hant-TW` (beta), `ru-RU` (beta), `vi-VN` (beta).
- **Advanced mode**: Speech recognition using a GenAI model. Currently only available on a very limited set of devices (e.g. Pixel 10). Supported locales: `en-US`, `ko-KR`, `es-ES`, `fr-FR`, `de-DE`, `it-IT`, `pt-PT`, `cmn-Hans-CN`, `cmn-Hant-TW`, `ja-JP`, `th-TH`, `ru-RU`, `nl-NL` (beta), `da-DK` (beta), `sv-SE` (beta), `pl-PL` (beta), `hi-IN` (beta), `vi-VN` (beta), `id-ID` (beta), `ar-SA` (beta), `tr-TR` (beta).

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device for the configured mode and locale.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-speech-recognition` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-speech-recognition
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`. Note that the basic recognition mode is only supported on devices with API level 31 or higher.

#### Permissions

The plugin declares the `android.permission.RECORD_AUDIO` permission in its manifest, so no manual configuration is needed. The microphone permission is requested automatically when you start a recognition session. You can also check and request the permission manually using the `checkPermissions()` and `requestPermissions()` methods.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiSpeechRecognitionVersion` version of `com.google.mlkit:genai-speech-recognition` (default: `1.0.0-alpha1`)
- `$kotlinVersion` version of the Kotlin Gradle plugin (default: `2.2.20`)

## Usage

The following example shows how to check the feature status, download the feature and run a speech recognition session.

### Check the feature status

Before using the speech recognition feature, check whether it is available on the device. The feature availability depends on the configured mode and locale:

```
import {
  FeatureStatus,
  GenAiSpeechRecognition,
  RecognitionMode,
} from '@capacitor-mlkit/genai-speech-recognition';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiSpeechRecognition.checkFeatureStatus({
    locale: 'en-US',
    mode: RecognitionMode.Basic,
  });
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiSpeechRecognition, RecognitionMode } from '@capacitor-mlkit/genai-speech-recognition';

const downloadFeature = async () => {
  await GenAiSpeechRecognition.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiSpeechRecognition.downloadFeature({
    locale: 'en-US',
    mode: RecognitionMode.Basic,
  });
};
```

### Start and stop a recognition session

Start a recognition session with `startRecognition(...)`. The audio is captured from the device microphone and the microphone permission is requested automatically if it has not been granted yet. Add listeners for the `partialResult` and `finalResult` events to receive the recognition results and for the `error` event to get notified about errors that occur during the session:

```
import { GenAiSpeechRecognition, RecognitionMode } from '@capacitor-mlkit/genai-speech-recognition';

const startRecognition = async () => {
  await GenAiSpeechRecognition.addListener('partialResult', event => {
    console.log('Partial result:', event.text);
  });
  await GenAiSpeechRecognition.addListener('finalResult', event => {
    console.log('Final result:', event.text);
  });
  await GenAiSpeechRecognition.addListener('error', event => {
    console.error('Error:', event.message);
  });
  await GenAiSpeechRecognition.startRecognition({
    locale: 'en-US',
    mode: RecognitionMode.Basic,
  });
};

const stopRecognition = async () => {
  await GenAiSpeechRecognition.stopRecognition();
};
```

## API

- [`checkFeatureStatus(...)`](#checkfeaturestatus)
- [`checkPermissions()`](#checkpermissions)
- [`downloadFeature(...)`](#downloadfeature)
- [`requestPermissions()`](#requestpermissions)
- [`startRecognition(...)`](#startrecognition)
- [`stopRecognition()`](#stoprecognition)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('error', ...)`](#addlistenererror-)
- [`addListener('finalResult', ...)`](#addlistenerfinalresult-)
- [`addListener('partialResult', ...)`](#addlistenerpartialresult-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)
- [Enums](#enums)

### checkFeatureStatus(...)

```
checkFeatureStatus(options?: FeatureOptions | undefined) => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the speech recognition feature.

The feature availability depends on the configured mode and locale. If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### checkPermissions()

```
checkPermissions() => Promise<PermissionStatus>
```

Check the status of the microphone permission.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature(...)

```
downloadFeature(options?: FeatureOptions | undefined) => Promise<void>
```

Download the speech recognition feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Since:** 8.2.0

______________________________________________________________________

### requestPermissions()

```
requestPermissions() => Promise<PermissionStatus>
```

Request the microphone permission.

Only available on Android.

**Returns:** `Promise<PermissionStatus>`

**Since:** 8.2.0

______________________________________________________________________

### startRecognition(...)

```
startRecognition(options?: FeatureOptions | undefined) => Promise<void>
```

Start a speech recognition session.

The audio is captured from the device microphone. If the microphone permission has not been granted yet, it will be requested automatically. The `partialResult` and `finalResult` event listeners will notify you about the recognition results. The `error` event listener will notify you about errors that occur during the session.

Rejects with the `RECOGNITION_ALREADY_RUNNING` error code if a recognition session is already running.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Since:** 8.2.0

______________________________________________________________________

### stopRecognition()

```
stopRecognition() => Promise<void>
```

Stop the current speech recognition session.

Only available on Android.

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the speech recognition feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('error', ...)

```
addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>
```

Called when an error occurs during a recognition session.

Only available on Android.

| Param              | Type                          |
| ------------------ | ----------------------------- |
| **`eventName`**    | `'error'`                     |
| **`listenerFunc`** | `(event: ErrorEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('finalResult', ...)

```
addListener(eventName: 'finalResult', listenerFunc: (event: RecognitionResultEvent) => void) => Promise<PluginListenerHandle>
```

Called when a final recognition result is available.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'finalResult'`                           |
| **`listenerFunc`** | `(event: RecognitionResultEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('partialResult', ...)

```
addListener(eventName: 'partialResult', listenerFunc: (event: RecognitionResultEvent) => void) => Promise<PluginListenerHandle>
```

Called when a partial recognition result is available.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'partialResult'`                         |
| **`listenerFunc`** | `(event: RecognitionResultEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                                        | Since |
| ------------------- | --------------- | ------------------------------------------------------------------ | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the speech recognition feature. | 8.2.0 |

#### FeatureOptions

The feature availability depends on the configured mode and locale. Therefore, `checkFeatureStatus(...)` and `downloadFeature(...)` take the same base options as `startRecognition(...)`.

| Prop         | Type              | Description                                                                                                          | Default                 | Since |
| ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----- |
| **`locale`** | `string`          | The locale of the speech to recognize as a BCP-47 language tag. The supported locales depend on the configured mode. | `The device locale.`    | 8.2.0 |
| **`mode`**   | `RecognitionMode` | The speech recognition mode.                                                                                         | `RecognitionMode.Basic` | 8.2.0 |

#### PermissionStatus

| Prop             | Type              | Description                              | Since |
| ---------------- | ----------------- | ---------------------------------------- | ----- |
| **`microphone`** | `PermissionState` | The status of the microphone permission. | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### ErrorEvent

| Prop          | Type     | Description        | Since |
| ------------- | -------- | ------------------ | ----- |
| **`message`** | `string` | The error message. | 8.2.0 |

#### RecognitionResultEvent

| Prop       | Type     | Description          | Since |
| ---------- | -------- | -------------------- | ----- |
| **`text`** | `string` | The recognized text. | 8.2.0 |

### Type Aliases

#### PermissionState

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### StartRecognitionOptions

`FeatureOptions`

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

#### RecognitionMode

| Members        | Value        | Description                                                                                                                                              | Since |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Advanced`** | `'ADVANCED'` | Speech recognition using a GenAI model. This mode provides the best quality but is currently only available on a limited set of devices (e.g. Pixel 10). | 8.2.0 |
| **`Basic`**    | `'BASIC'`    | Speech recognition using a traditional speech model. This mode requires Android API level 31 or higher.                                                  | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The speech recognition is performed entirely on-device. The basic mode requires Android API level 31 or higher. The advanced mode uses a GenAI model and is currently only available on a very limited set of devices (e.g. Pixel 10). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device (see [Requirements](#requirements)).

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### What is the difference between the basic and advanced mode?

The basic mode uses a traditional on-device speech model and is supported on Android devices with API level 31 or higher. The advanced mode uses a GenAI model, which provides the best quality but is currently only available on a very limited set of devices (e.g. Pixel 10). Each mode supports a different set of locales (see [Requirements](#requirements)).

### How do I receive the recognition results?

Add listeners for the `partialResult` and `finalResult` events before calling `startRecognition(...)`. The `partialResult` event is called with intermediate results while the user is speaking. The `finalResult` event is called with the final recognized text.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Unofficial Capacitor plugin for ML Kit Translation.
- [Language Identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/): Unofficial Capacitor plugin for ML Kit Language Identification.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-speech-recognition/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-speech-recognition/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit GenAI Summarization Plugin

Unofficial Capacitor plugin for [ML Kit GenAI Summarization](https://developers.google.com/ml-kit/genai/summarization).[1](#fn:1)

> [!WARNING] The ML Kit GenAI APIs are currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The GenAI Summarization plugin is typically used to summarize text on-device using Gemini Nano, for example:

- **Article summaries**: Give users a quick overview of long articles or documents in one to three bullet points.
- **Chat recaps**: Summarize long chat conversations so users can catch up at a glance.
- **Note-taking**: Condense meeting notes or transcripts into their key points.

## Requirements

This plugin uses [Gemini Nano](https://developers.google.com/ml-kit/genai), which runs entirely on-device. It is only available on Android and has the following device requirements:

- The device must support Gemini Nano (see [supported devices](https://developers.google.com/ml-kit/genai#supported_devices)).
- The device must run Android API level 26 or higher.
- The device must not have an unlocked bootloader.

Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/genai-summarization` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/genai-summarization
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 26. Make sure to set the `minSdkVersion` in your `variables.gradle` file to at least `26`.

#### Variables

This plugin will use the following project variables (defined in your app’s `variables.gradle` file):

- `$mlkitGenaiSummarizationVersion` version of `com.google.mlkit:genai-summarization` (default: `1.0.0-beta1`)

## Usage

The following example shows how to check the feature status, download the feature and summarize a text.

### Check the feature status

Before using the summarization feature, check whether it is available on the device. The feature availability depends on the configured input type, output type and language:

```
import {
  FeatureStatus,
  GenAiSummarization,
  InputType,
  Language,
  OutputType,
} from '@capacitor-mlkit/genai-summarization';

const checkFeatureStatus = async () => {
  const { featureStatus } = await GenAiSummarization.checkFeatureStatus({
    inputType: InputType.Article,
    language: Language.English,
    outputType: OutputType.ThreeBullets,
  });
  return featureStatus === FeatureStatus.Available;
};
```

### Download the feature

If the feature status is `DOWNLOADABLE`, download the feature before using it. Add a listener for the `downloadProgress` event to get notified about the download progress:

```
import { GenAiSummarization, InputType, Language, OutputType } from '@capacitor-mlkit/genai-summarization';

const downloadFeature = async () => {
  await GenAiSummarization.addListener('downloadProgress', event => {
    console.log('Total bytes downloaded:', event.totalBytesDownloaded);
  });
  await GenAiSummarization.downloadFeature({
    inputType: InputType.Article,
    language: Language.English,
    outputType: OutputType.ThreeBullets,
  });
};
```

### Summarize a text

Pass the text to `summarize(...)` to generate a summary. Add a listener for the `inferenceProgress` event to receive partial results as they are generated:

```
import { GenAiSummarization, InputType, Language, OutputType } from '@capacitor-mlkit/genai-summarization';

const summarize = async () => {
  await GenAiSummarization.addListener('inferenceProgress', event => {
    console.log('Partial result:', event.text);
  });
  const { summary } = await GenAiSummarization.summarize({
    text: 'Capacitor is an open source native runtime for building Web Native apps. Create cross-platform iOS, Android, and Progressive Web Apps with JavaScript, HTML, and CSS.',
    inputType: InputType.Article,
    language: Language.English,
    outputType: OutputType.ThreeBullets,
  });
  return summary;
};
```

## API

- [`checkFeatureStatus(...)`](#checkfeaturestatus)
- [`downloadFeature(...)`](#downloadfeature)
- [`summarize(...)`](#summarize)
- [`addListener('downloadProgress', ...)`](#addlistenerdownloadprogress-)
- [`addListener('inferenceProgress', ...)`](#addlistenerinferenceprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### checkFeatureStatus(...)

```
checkFeatureStatus(options?: FeatureOptions | undefined) => Promise<CheckFeatureStatusResult>
```

Check the current availability status of the summarization feature.

If the status is `DOWNLOADABLE`, you can download the feature using `downloadFeature(...)`.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Returns:** `Promise<CheckFeatureStatusResult>`

**Since:** 8.2.0

______________________________________________________________________

### downloadFeature(...)

```
downloadFeature(options?: FeatureOptions | undefined) => Promise<void>
```

Download the summarization feature.

The `downloadProgress` event listener will notify you about the download progress. The returned promise resolves when the download is complete or the feature is already available.

Only available on Android.

| Param         | Type             |
| ------------- | ---------------- |
| **`options`** | `FeatureOptions` |

**Since:** 8.2.0

______________________________________________________________________

### summarize(...)

```
summarize(options: SummarizeOptions) => Promise<SummarizeResult>
```

Summarize the given text.

The `inferenceProgress` event listener will notify you about partial results as they are generated. The returned promise resolves with the full result.

Only available on Android.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SummarizeOptions` |

**Returns:** `Promise<SummarizeResult>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('downloadProgress', ...)

```
addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called while the summarization feature is being downloaded.

Only available on Android.

| Param              | Type                                     |
| ------------------ | ---------------------------------------- |
| **`eventName`**    | `'downloadProgress'`                     |
| **`listenerFunc`** | `(event: DownloadProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### addListener('inferenceProgress', ...)

```
addListener(eventName: 'inferenceProgress', listenerFunc: (event: InferenceProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when a new partial result is available during inference.

Only available on Android.

| Param              | Type                                      |
| ------------------ | ----------------------------------------- |
| **`eventName`**    | `'inferenceProgress'`                     |
| **`listenerFunc`** | `(event: InferenceProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 8.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### CheckFeatureStatusResult

| Prop                | Type            | Description                                                   | Since |
| ------------------- | --------------- | ------------------------------------------------------------- | ----- |
| **`featureStatus`** | `FeatureStatus` | The current availability status of the summarization feature. | 8.2.0 |

#### FeatureOptions

The feature availability depends on the configured input type, output type and language. Therefore, `checkFeatureStatus(...)` and `downloadFeature(...)` take the same base options as `summarize(...)`.

| Prop             | Type         | Description                     | Default                | Since |
| ---------------- | ------------ | ------------------------------- | ---------------------- | ----- |
| **`inputType`**  | `InputType`  | The type of the input text.     | `InputType.Article`    | 8.2.0 |
| **`language`**   | `Language`   | The language of the input text. | `Language.English`     | 8.2.0 |
| **`outputType`** | `OutputType` | The type of the output summary. | `OutputType.OneBullet` | 8.2.0 |

#### SummarizeResult

| Prop          | Type     | Description                    | Since |
| ------------- | -------- | ------------------------------ | ----- |
| **`summary`** | `string` | The summary of the input text. | 8.2.0 |

#### SummarizeOptions

| Prop       | Type     | Description                                                                                 | Since |
| ---------- | -------- | ------------------------------------------------------------------------------------------- | ----- |
| **`text`** | `string` | The text to summarize. The input must be under 4,000 tokens (or about 3,000 English words). | 8.2.0 |

#### PluginListenerHandle

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

#### DownloadProgressEvent

| Prop                       | Type     | Description                                  | Since |
| -------------------------- | -------- | -------------------------------------------- | ----- |
| **`totalBytesDownloaded`** | `number` | The total number of bytes downloaded so far. | 8.2.0 |

#### InferenceProgressEvent

| Prop       | Type     | Description                         | Since |
| ---------- | -------- | ----------------------------------- | ----- |
| **`text`** | `string` | The new text of the partial result. | 8.2.0 |

### Enums

#### FeatureStatus

| Members            | Value            | Description                                                 | Since |
| ------------------ | ---------------- | ----------------------------------------------------------- | ----- |
| **`Available`**    | `'AVAILABLE'`    | The feature is available to use.                            | 8.2.0 |
| **`Downloadable`** | `'DOWNLOADABLE'` | The feature can be downloaded using `downloadFeature(...)`. | 8.2.0 |
| **`Downloading`**  | `'DOWNLOADING'`  | The feature is currently being downloaded.                  | 8.2.0 |
| **`Unavailable`**  | `'UNAVAILABLE'`  | The feature is not available on this device.                | 8.2.0 |

#### InputType

| Members            | Value            | Description                                                                                       | Since |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------- | ----- |
| **`Article`**      | `'ARTICLE'`      | The input text is an article.                                                                     | 8.2.0 |
| **`Conversation`** | `'CONVERSATION'` | The input text is a conversation where each line uses the format `&lt;name&gt;: &lt;message&gt;`. | 8.2.0 |

#### Language

| Members        | Value        | Since |
| -------------- | ------------ | ----- |
| **`English`**  | `'ENGLISH'`  | 8.2.0 |
| **`Japanese`** | `'JAPANESE'` | 8.2.0 |
| **`Korean`**   | `'KOREAN'`   | 8.2.0 |

#### OutputType

| Members            | Value             | Description                                        | Since |
| ------------------ | ----------------- | -------------------------------------------------- | ----- |
| **`OneBullet`**    | `'ONE_BULLET'`    | The summary consists of one bullet point.          | 8.2.0 |
| **`TwoBullets`**   | `'TWO_BULLETS'`   | The summary consists of up to two bullet points.   | 8.2.0 |
| **`ThreeBullets`** | `'THREE_BULLETS'` | The summary consists of up to three bullet points. | 8.2.0 |

## FAQ

### What are the requirements to use this plugin?

The summarization is performed on-device by Gemini Nano. This requires a device that supports Gemini Nano, Android API level 26 or higher and a locked bootloader (see [Requirements](#requirements)). Use the `checkFeatureStatus(...)` method to check whether the feature is available on the device.

### Why is this plugin only available on Android?

The ML Kit GenAI APIs are based on Gemini Nano and AICore, which are currently only available on Android. On iOS and Web, all methods reject with an appropriate error.

### How large can the input text be?

The input must be under 4,000 tokens (or about 3,000 English words). For articles, the input should contain at least 400 characters for the best results.

### How do I get the summary as a stream?

Add a listener for the `inferenceProgress` event before calling `summarize(...)`. The listener is called with each partial result as it is generated. The promise returned by `summarize(...)` resolves with the full result.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Unofficial Capacitor plugin for ML Kit Translation.
- [Smart Reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/): Unofficial Capacitor plugin for ML Kit Smart Reply.
- [GenAI Proofreading](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-proofreading/): Proofread text before or after summarizing it.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-summarization/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/genai-summarization/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Image Labeling Plugin

Unofficial Capacitor plugin for [ML Kit Image Labeling](https://developers.google.com/ml-kit/vision/image-labeling).[1](#fn:1)

## Use Cases

The Image Labeling plugin is typically used whenever an app needs to understand the content of an image, for example:

- **Content categorization**: Automatically tag and organize photos by the objects, places, or activities they contain.
- **Accessibility**: Generate descriptive labels for images to support screen readers and other assistive technologies.
- **Content moderation**: Detect the presence of certain objects or scenes before an image is published.
- **Search and discovery**: Make an image library searchable by the labels detected in each image.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/image-labeling` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/image-labeling
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitImageLabelingVersion` version of `com.google.mlkit:image-labeling` (default: `17.0.9`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to detect labels in an image.

### Detect labels in an image

Detect labels in an image at a local path. You can configure the confidence threshold to control which labels are returned. Only available on Android and iOS:

```
import { ImageLabeling } from '@capacitor-mlkit/image-labeling';

const processImage = async () => {
  const { labels } = await ImageLabeling.processImage({
    path: 'path/to/image.jpg',
    confidenceThreshold: 0.5,
  });
  return labels;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Detects labels in the supplied image.

Labels can describe objects, locations, activities, animal species, products and more.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop         | Type           | Description          | Since |
| ------------ | -------------- | -------------------- | ----- |
| **`labels`** | `ImageLabel[]` | The detected labels. | 8.2.0 |

#### ImageLabel

Represents a label detected in an image.

| Prop             | Type     | Description                                                            | Since |
| ---------------- | -------- | ---------------------------------------------------------------------- | ----- |
| **`index`**      | `number` | The index of the label within the model.                               | 8.2.0 |
| **`text`**       | `string` | The text of the label (e.g. `Bicycle`). The text is always in English. | 8.2.0 |
| **`confidence`** | `number` | The confidence of the label. The value is between `0.0` and `1.0`.     | 8.2.0 |

#### ProcessImageOptions

| Prop                      | Type     | Description                                                                                                                                                         | Default | Since |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`path`**                | `string` | The local path to the image file.                                                                                                                                   |         | 8.2.0 |
| **`confidenceThreshold`** | `number` | The confidence threshold for the labels. Only labels with a confidence greater than or equal to this value are returned. The value must be between `0.0` and `1.0`. | `0.5`   | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android and iOS. The Web platform is not supported by the underlying ML Kit Image Labeling SDK.

### Which model does the plugin use?

The plugin uses the base image labeling model, which is bundled with the app and can recognize more than 400 labels covering objects, places, activities, animal species, products, and more. Custom TensorFlow Lite models are currently not supported.

### What does the confidence threshold do?

The `confidenceThreshold` option controls which labels are returned. Only labels with a confidence greater than or equal to the threshold are included in the result. The value must be between `0.0` and `1.0` and defaults to `0.5`.

### In which language are the labels returned?

The label text is always returned in English. Use the `index` property of a label together with your own localized lookup table if you need translated labels.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes with ML Kit Barcode Scanning.
- [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Detect faces in images with ML Kit Face Detection.
- [ML Kit Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/): Separate subjects from the background with ML Kit Subject Segmentation.
- [ML Kit Text Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/text-recognition/): Recognize text in images alongside general image labels.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/image-labeling/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/image-labeling/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Language Identification Plugin

Unofficial Capacitor plugin for [ML Kit Language Identification](https://developers.google.com/ml-kit/language/identification).[1](#fn:1)

## Use Cases

The Language Identification plugin determines the language of a string of text directly on the device, for example:

- **Localization**: Detect the language of user-generated content to display it correctly.
- **Translation**: Determine the source language before translating a text.
- **Content routing**: Route messages to the right agent or bot based on their language.
- **Smart Reply**: Check whether a conversation is in a supported language before generating reply suggestions.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/language-identification` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/language-identification
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitLanguageIdVersion` version of `com.google.mlkit:language-id` (default: `17.0.6`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The language identification model ships with the SDK, so no model download is required.

```
import { LanguageIdentification } from '@capacitor-mlkit/language-identification';

const identifyLanguage = async () => {
  const { language } = await LanguageIdentification.identifyLanguage({
    text: 'Wie geht es dir?',
  });
  // `language` is a BCP-47 tag (e.g. `de`) or `und` if no language met the threshold.
  return language;
};

const identifyPossibleLanguages = async () => {
  const { identifiedLanguages } =
    await LanguageIdentification.identifyPossibleLanguages({
      text: 'Wie geht es dir?',
    });
  return identifiedLanguages;
};
```

The returned language is a [BCP-47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) such as `en`, `de` or `zh`. If no language could be identified with sufficient confidence, the value `und` (undetermined) is returned.

## API

- [`identifyLanguage(...)`](#identifylanguage)
- [`identifyPossibleLanguages(...)`](#identifypossiblelanguages)
- [Interfaces](#interfaces)

### identifyLanguage(...)

```
identifyLanguage(options: IdentifyLanguageOptions) => Promise<IdentifyLanguageResult>
```

Identify the most likely language of the given text.

Only available on Android and iOS.

| Param         | Type                      |
| ------------- | ------------------------- |
| **`options`** | `IdentifyLanguageOptions` |

**Returns:** `Promise<IdentifyLanguageResult>`

**Since:** 8.2.0

______________________________________________________________________

### identifyPossibleLanguages(...)

```
identifyPossibleLanguages(options: IdentifyPossibleLanguagesOptions) => Promise<IdentifyPossibleLanguagesResult>
```

Identify all possible languages of the given text with their confidence.

Only available on Android and iOS.

| Param         | Type                               |
| ------------- | ---------------------------------- |
| **`options`** | `IdentifyPossibleLanguagesOptions` |

**Returns:** `Promise<IdentifyPossibleLanguagesResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### IdentifyLanguageResult

| Prop           | Type     | Description                                                                                                                           | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`language`** | `string` | The BCP-47 language tag of the most likely language. The value is `'und'` (undetermined) if no language met the confidence threshold. | 8.2.0 |

#### IdentifyLanguageOptions

| Prop                      | Type     | Description                                                                                                                                                       | Default | Since |
| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`text`**                | `string` | The text to identify the language for.                                                                                                                            |         | 8.2.0 |
| **`confidenceThreshold`** | `number` | The confidence threshold (`0.0` to `1.0`) a language must meet to be returned. If no language meets the threshold, the `language` will be `'und'` (undetermined). | `0.5`   | 8.2.0 |

#### IdentifyPossibleLanguagesResult

| Prop                      | Type                   | Description                                                                                                                                                                        | Since |
| ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`identifiedLanguages`** | `IdentifiedLanguage[]` | The identified languages ordered by descending confidence. The array contains a single entry with the language `'und'` (undetermined) if no language met the confidence threshold. | 8.2.0 |

#### IdentifiedLanguage

| Prop             | Type     | Description                                                 | Since |
| ---------------- | -------- | ----------------------------------------------------------- | ----- |
| **`language`**   | `string` | The BCP-47 language tag of the identified language.         | 8.2.0 |
| **`confidence`** | `number` | The confidence (`0.0` to `1.0`) of the identified language. | 8.2.0 |

#### IdentifyPossibleLanguagesOptions

| Prop                      | Type     | Description                                                                    | Default | Since |
| ------------------------- | -------- | ------------------------------------------------------------------------------ | ------- | ----- |
| **`text`**                | `string` | The text to identify the languages for.                                        |         | 8.2.0 |
| **`confidenceThreshold`** | `number` | The confidence threshold (`0.0` to `1.0`) a language must meet to be returned. | `0.01`  | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. The `identifyLanguage(...)` and `identifyPossibleLanguages(...)` methods are only available on Android and iOS, so there is no web implementation.

### Which languages are supported?

The model can identify [more than 100 languages](https://developers.google.com/ml-kit/language/identification/langid-support). The returned value is a BCP-47 language tag.

### What does `und` mean?

`und` stands for *undetermined*. It is returned when no language could be identified with a confidence above the configured threshold.

### Do I need to download a model?

No. The language identification model is bundled with the SDK, so no model download or management is required.

### How can I change the confidence threshold?

Both methods accept an optional `confidenceThreshold` (between `0.0` and `1.0`). The default is `0.5` for `identifyLanguage(...)` and `0.01` for `identifyPossibleLanguages(...)`.

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Translate text once its language has been identified.
- [Smart Reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/): Generate reply suggestions for a conversation.
- [ML Kit Digital Ink Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/digital-ink-recognition/): Recognize handwriting, then identify the language of the recognized text.
- [GenAI Speech Recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-speech-recognition/): Transcribe speech, then identify the language of the transcript.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/language-identification/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/language-identification/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Object Detection Plugin

Unofficial Capacitor plugin for [ML Kit Object Detection and Tracking](https://developers.google.com/ml-kit/vision/object-detection).[1](#fn:1)

## Use Cases

The Object Detection plugin is typically used whenever an app needs to locate and classify the prominent objects in an image, for example:

- **Visual search**: Let users draw a box around an object in a photo and search for similar products.
- **Content categorization**: Automatically tag images by the objects they contain (fashion goods, food, plants, and more).
- **Image cropping**: Use the bounding box of the most prominent object to automatically crop or focus an image.
- **Inventory management**: Detect and count objects in a photo to support cataloging workflows.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/object-detection` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/object-detection
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitObjectDetectionVersion` version of `com.google.mlkit:object-detection` (default: `17.0.2`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to detect objects in an image.

### Detect objects in an image

Detect objects in an image at a local path. You can optionally enable classification and the detection of multiple objects. Only available on Android and iOS:

```
import { ObjectDetection } from '@capacitor-mlkit/object-detection';

const processImage = async () => {
  const { detectedObjects } = await ObjectDetection.processImage({
    path: 'path/to/image.jpg',
    shouldEnableClassification: true,
    shouldEnableMultipleObjects: true,
  });
  return detectedObjects;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Detects objects in the supplied image.

Each detected object is localized with a bounding box and, if classification is enabled, labeled with one of five coarse categories.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop                  | Type               | Description           | Since |
| --------------------- | ------------------ | --------------------- | ----- |
| **`detectedObjects`** | `DetectedObject[]` | The detected objects. | 8.2.0 |

#### DetectedObject

Represents an object detected in an image.

| Prop              | Type            | Description                                                                                          | Since |
| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------- | ----- |
| **`boundingBox`** | `Rect`          | The bounding box of the detected object.                                                             | 8.2.0 |
| **`trackingId`**  | `number`        | The tracking identifier of the detected object. Only set when the object is detected in stream mode. | 8.2.0 |
| **`labels`**      | `ObjectLabel[]` | The labels of the detected object. The list is empty if classification is disabled.                  | 8.2.0 |

#### Rect

Represents a rectangle.

| Prop         | Type     | Description                                       | Since |
| ------------ | -------- | ------------------------------------------------- | ----- |
| **`left`**   | `number` | The left coordinate of the rectangle in pixels.   | 8.2.0 |
| **`top`**    | `number` | The top coordinate of the rectangle in pixels.    | 8.2.0 |
| **`right`**  | `number` | The right coordinate of the rectangle in pixels.  | 8.2.0 |
| **`bottom`** | `number` | The bottom coordinate of the rectangle in pixels. | 8.2.0 |

#### ObjectLabel

Represents a label of a detected object.

| Prop             | Type     | Description                                                         | Since |
| ---------------- | -------- | ------------------------------------------------------------------- | ----- |
| **`index`**      | `number` | The index of the label.                                             | 8.2.0 |
| **`text`**       | `string` | The text of the label (e.g. `Food`). The text is always in English. | 8.2.0 |
| **`confidence`** | `number` | The confidence of the label. The value is between `0.0` and `1.0`.  | 8.2.0 |

#### ProcessImageOptions

| Prop                              | Type      | Description                                                                                                                                                                     | Default | Since |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **`path`**                        | `string`  | The local path to the image file.                                                                                                                                               |         | 8.2.0 |
| **`shouldEnableClassification`**  | `boolean` | Whether to classify the detected objects into coarse categories. Classification returns only five coarse categories (`Fashion good`, `Food`, `Home good`, `Place` and `Plant`). | `false` | 8.2.0 |
| **`shouldEnableMultipleObjects`** | `boolean` | Whether to detect multiple objects instead of only the most prominent one. When enabled, up to five objects are detected.                                                       | `false` | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android and iOS. The Web platform is not supported by the underlying ML Kit Object Detection SDK.

### Which model does the plugin use?

The plugin uses the base object detection and tracking model, which is bundled with the app. Custom TensorFlow Lite classifier models are currently not supported.

### Which categories does classification return?

When `shouldEnableClassification` is enabled, the base model classifies detected objects into only five coarse categories: `Fashion good`, `Food`, `Home good`, `Place`, and `Plant`. Any object that does not fall into one of these categories receives no label.

### Why is the `trackingId` not set?

The plugin processes still images in single-image mode, where objects are not tracked across frames. The `trackingId` is therefore not set. It is only populated when objects are detected in stream mode, which is not supported by this plugin.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes with ML Kit Barcode Scanning.
- [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Detect faces in images with ML Kit Face Detection.
- [ML Kit Image Labeling](https://capawesome.io/docs/sdks/capacitor/mlkit/image-labeling/): Detect labels in images with ML Kit Image Labeling.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/object-detection/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/object-detection/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Pose Detection Plugin

Unofficial Capacitor plugin for [ML Kit Pose Detection](https://developers.google.com/ml-kit/vision/pose-detection).[1](#fn:1)

> [!WARNING] The ML Kit Pose Detection API is currently in **beta**. The API surface and behavior may change in future releases.

## Use Cases

The Pose Detection plugin is typically used whenever an app needs to track the position of a person's body in an image, for example:

- **Fitness tracking**: Analyze a user's posture and body position while they exercise.
- **Gesture recognition**: Detect body gestures to control an app or a game.
- **Augmented reality**: Overlay effects or clothing on top of a person's body.
- **Physical therapy**: Monitor a patient's movements and range of motion.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/pose-detection` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/pose-detection
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### Variables

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

- `$mlkitPoseDetectionVersion` version of `com.google.mlkit:pose-detection` (default: `18.0.0-beta5`)
- `$mlkitPoseDetectionAccurateVersion` version of `com.google.mlkit:pose-detection-accurate` (default: `18.0.0-beta5`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to detect the pose of a person in an image.

### Detect a pose in an image

Detect the pose of a person in an image at a local path. You can optionally select the performance mode of the pose detector. Only available on Android and iOS:

```
import { PoseDetection, PerformanceMode } from '@capacitor-mlkit/pose-detection';

const processImage = async () => {
  const { poses } = await PoseDetection.processImage({
    path: 'path/to/image.jpg',
    performanceMode: PerformanceMode.Base,
  });
  return poses;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)
- [Enums](#enums)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Detects the pose of a person in the supplied image.

The API detects the pose of a single (most prominent) person and returns all 33 skeletal landmarks with their positions.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop        | Type     | Description                                                                                                               | Since |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`poses`** | `Pose[]` | The detected poses. The array contains either zero or one pose, because the API only detects the pose of a single person. | 8.2.0 |

#### Pose

Represents a pose detected in an image.

| Prop            | Type             | Description                                                                     | Since |
| --------------- | ---------------- | ------------------------------------------------------------------------------- | ----- |
| **`landmarks`** | `PoseLandmark[]` | The detected landmarks of the pose. The array always contains all 33 landmarks. | 8.2.0 |

#### PoseLandmark

Represents a landmark of a detected pose.

| Prop                    | Type               | Description                                                                                                                                                                                     | Since |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`type`**              | `PoseLandmarkType` | The type of the landmark (e.g. `NOSE`).                                                                                                                                                         | 8.2.0 |
| **`x`**                 | `number`           | The x coordinate of the landmark in the image in pixels.                                                                                                                                        | 8.2.0 |
| **`y`**                 | `number`           | The y coordinate of the landmark in the image in pixels.                                                                                                                                        | 8.2.0 |
| **`z`**                 | `number`           | The z coordinate of the landmark. The value represents the depth of the landmark. The smaller the value, the closer the landmark is to the camera. The origin is the midpoint between the hips. | 8.2.0 |
| **`inFrameLikelihood`** | `number`           | The likelihood that the landmark is within the image frame. The value is between `0.0` and `1.0`.                                                                                               | 8.2.0 |

#### ProcessImageOptions

| Prop                  | Type              | Description                                | Default                | Since |
| --------------------- | ----------------- | ------------------------------------------ | ---------------------- | ----- |
| **`path`**            | `string`          | The local path to the image file.          |                        | 8.2.0 |
| **`performanceMode`** | `PerformanceMode` | The performance mode of the pose detector. | `PerformanceMode.Base` | 8.2.0 |

### Enums

#### PoseLandmarkType

| Members              | Value                |
| -------------------- | -------------------- |
| **`Nose`**           | `'NOSE'`             |
| **`LeftEyeInner`**   | `'LEFT_EYE_INNER'`   |
| **`LeftEye`**        | `'LEFT_EYE'`         |
| **`LeftEyeOuter`**   | `'LEFT_EYE_OUTER'`   |
| **`RightEyeInner`**  | `'RIGHT_EYE_INNER'`  |
| **`RightEye`**       | `'RIGHT_EYE'`        |
| **`RightEyeOuter`**  | `'RIGHT_EYE_OUTER'`  |
| **`LeftEar`**        | `'LEFT_EAR'`         |
| **`RightEar`**       | `'RIGHT_EAR'`        |
| **`LeftMouth`**      | `'LEFT_MOUTH'`       |
| **`RightMouth`**     | `'RIGHT_MOUTH'`      |
| **`LeftShoulder`**   | `'LEFT_SHOULDER'`    |
| **`RightShoulder`**  | `'RIGHT_SHOULDER'`   |
| **`LeftElbow`**      | `'LEFT_ELBOW'`       |
| **`RightElbow`**     | `'RIGHT_ELBOW'`      |
| **`LeftWrist`**      | `'LEFT_WRIST'`       |
| **`RightWrist`**     | `'RIGHT_WRIST'`      |
| **`LeftPinky`**      | `'LEFT_PINKY'`       |
| **`RightPinky`**     | `'RIGHT_PINKY'`      |
| **`LeftIndex`**      | `'LEFT_INDEX'`       |
| **`RightIndex`**     | `'RIGHT_INDEX'`      |
| **`LeftThumb`**      | `'LEFT_THUMB'`       |
| **`RightThumb`**     | `'RIGHT_THUMB'`      |
| **`LeftHip`**        | `'LEFT_HIP'`         |
| **`RightHip`**       | `'RIGHT_HIP'`        |
| **`LeftKnee`**       | `'LEFT_KNEE'`        |
| **`RightKnee`**      | `'RIGHT_KNEE'`       |
| **`LeftAnkle`**      | `'LEFT_ANKLE'`       |
| **`RightAnkle`**     | `'RIGHT_ANKLE'`      |
| **`LeftHeel`**       | `'LEFT_HEEL'`        |
| **`RightHeel`**      | `'RIGHT_HEEL'`       |
| **`LeftFootIndex`**  | `'LEFT_FOOT_INDEX'`  |
| **`RightFootIndex`** | `'RIGHT_FOOT_INDEX'` |

#### PerformanceMode

| Members        | Value        | Description                                     | Since |
| -------------- | ------------ | ----------------------------------------------- | ----- |
| **`Base`**     | `'BASE'`     | The base model is faster but less accurate.     | 8.2.0 |
| **`Accurate`** | `'ACCURATE'` | The accurate model is slower but more accurate. | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android and iOS. The Web platform is not supported by the underlying ML Kit Pose Detection SDK.

### Which models does the plugin use?

The plugin bundles both the **base** and the **accurate** pose detection models. You can select the model at runtime via the `performanceMode` option. The base model is faster but less accurate, while the accurate model is slower but more accurate.

### How much does the plugin increase the app size?

The pose detection models are bundled with the app and increase the app size. The base model adds around 10 MB and the accurate model adds around 26 MB.

### How many people can the plugin detect?

The ML Kit Pose Detection API only detects the pose of a single (most prominent) person in an image. If you need to detect the pose of multiple people, this plugin is not suitable.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes with ML Kit Barcode Scanning.
- [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Detect faces in images with ML Kit Face Detection.
- [ML Kit Object Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/object-detection/): Detect and track objects in images with ML Kit Object Detection.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/pose-detection/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/pose-detection/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Selfie Segmentation Plugin

Unofficial Capacitor plugin for [ML Kit Selfie Segmentation](https://developers.google.com/ml-kit/vision/selfie-segmentation).[1](#fn:1)

## Use Cases

The Selfie Segmentation plugin is typically used to separate a person from the background of a photo, for example:

- **Background removal**: Remove or replace the background of a selfie, for example for profile pictures or avatars.
- **Photo effects**: Build editing features that combine the segmented image with new backgrounds or overlays.
- **Sticker creation**: Turn selfies into cutouts or stickers that users can share in chats and posts.

## 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     |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/selfie-segmentation` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/selfie-segmentation
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitSelfieSegmentationVersion` version of `com.google.mlkit:segmentation-selfie` (default: `16.0.0-beta6`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Usage

The following example shows how to segment a person from the background.

### Segment a person from the background

Pass the local path of an image file to `processImage(...)` to perform the segmentation. You can optionally scale the image using the `width` and `height` options and adjust the confidence threshold. The result contains the path to the segmented image file along with its width and height. Only available on Android and iOS:

```
import { SelfieSegmentation } from '@capacitor-mlkit/selfie-segmentation';

const processImage = async () => {
  const { path } = await SelfieSegmentation.processImage({
    path: 'path/to/image.jpg',
    confidence: 0.7,
  });
  return path;
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Performs segmentation on an input image.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 5.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop         | Type     | Description                           | Since |
| ------------ | -------- | ------------------------------------- | ----- |
| **`path`**   | `string` | The path to the segmented image file. | 5.2.0 |
| **`width`**  | `number` | Returns the width of the image file.  | 5.2.0 |
| **`height`** | `number` | Returns the height of the image file. | 5.2.0 |

#### ProcessImageOptions

| Prop             | Type     | Description                                                                               | Default | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------- | ------- | ----- |
| **`path`**       | `string` | The local path to the image file.                                                         |         | 5.2.0 |
| **`width`**      | `number` | Scale the image to this width. If no `height` is given, it will respect the aspect ratio. |         | 5.2.0 |
| **`height`**     | `number` | Scale the image to this height. If no `width` is given, it will respect the aspect ratio. |         | 5.2.0 |
| **`confidence`** | `number` | Sets the confidence threshold.                                                            | `0.9`   | 5.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. The `processImage(...)` method is only available on Android and iOS, so there is no web implementation.

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

### How can I adjust the accuracy of the segmentation?

You can set the confidence threshold using the `confidence` option of the `processImage(...)` method. The default value is `0.9`. Experiment with different values to find the best result for your images.

### How can I scale the image before it is processed?

Use the `width` and `height` options of the `processImage(...)` method to scale the image. If only one of the two values is given, the aspect ratio of the image is respected.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/): Unofficial Capacitor plugin for ML Kit Subject Segmentation.
- [Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Unofficial Capacitor plugin for ML Kit Face Detection.
- [Face Mesh Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/): Unofficial Capacitor plugin for ML Kit Face Mesh Detection.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/selfie-segmentation/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/selfie-segmentation/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Smart Reply Plugin

Unofficial Capacitor plugin for [ML Kit Smart Reply](https://developers.google.com/ml-kit/language/smart-reply).[1](#fn:1)

## Use Cases

The Smart Reply plugin generates contextual reply suggestions for a conversation directly on the device, for example:

- **Messaging apps**: Offer quick reply suggestions below an incoming message.
- **Customer support**: Help agents respond faster with suggested replies.
- **Wearables**: Provide tappable reply chips where typing is inconvenient.
- **Chatbots**: Suggest follow-up responses based on the recent conversation.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/smart-reply` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/smart-reply
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitSmartReplyVersion` version of `com.google.mlkit:smart-reply` (default: `17.0.4`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to generate reply suggestions for a conversation between two users.

Smart Reply only supports conversations in **English**. For any other language, the `status` will be `NOT_SUPPORTED_LANGUAGE` and no suggestions are returned. Reply suggestions are only generated for the messages of remote users (`isLocalUser: false`), so remote messages must provide a stable `userId`.

```
import {
  SmartReply,
  SmartReplySuggestionResultStatus,
} from '@capacitor-mlkit/smart-reply';

const suggestReplies = async () => {
  const { status, suggestions } = await SmartReply.suggestReplies({
    messages: [
      {
        text: 'Are you free for lunch today?',
        timestamp: Date.now() - 60_000,
        isLocalUser: false,
        userId: 'user-1',
      },
      {
        text: 'Sure, where do you want to go?',
        timestamp: Date.now() - 30_000,
        isLocalUser: true,
      },
      {
        text: 'How about the new place downtown?',
        timestamp: Date.now(),
        isLocalUser: false,
        userId: 'user-1',
      },
    ],
  });

  if (status === SmartReplySuggestionResultStatus.Success) {
    return suggestions;
  }
  return [];
};
```

## API

- [`suggestReplies(...)`](#suggestreplies)
- [Interfaces](#interfaces)
- [Enums](#enums)

### suggestReplies(...)

```
suggestReplies(options: SuggestRepliesOptions) => Promise<SuggestRepliesResult>
```

Generate reply suggestions for a conversation.

Smart Reply only supports conversations in English. If the conversation is in another language or no suitable reply is found, the `status` will reflect this and `suggestions` will be empty.

Only available on Android and iOS.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `SuggestRepliesOptions` |

**Returns:** `Promise<SuggestRepliesResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### SuggestRepliesResult

| Prop              | Type                               | Description                                                                                              | Since |
| ----------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | ----- |
| **`status`**      | `SmartReplySuggestionResultStatus` | The status of the suggestion generation.                                                                 | 8.2.0 |
| **`suggestions`** | `string[]`                         | The generated reply suggestions. Contains up to 3 suggestions and is empty unless `status` is `SUCCESS`. | 8.2.0 |

#### SuggestRepliesOptions

| Prop           | Type            | Description                                                                                                                                                        | Since |
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`messages`** | `TextMessage[]` | The recent messages of the conversation in chronological order (oldest first). Only the last 10 messages are considered by the model. The array must not be empty. | 8.2.0 |

#### TextMessage

| Prop              | Type      | Description                                                                                                             | Since |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**        | `string`  | The text content of the message.                                                                                        | 8.2.0 |
| **`timestamp`**   | `number`  | The time the message was sent in milliseconds since epoch.                                                              | 8.2.0 |
| **`isLocalUser`** | `boolean` | Whether the message was sent by the local user. Reply suggestions are only generated for messages sent by remote users. | 8.2.0 |
| **`userId`**      | `string`  | A stable identifier of the user who sent the message. Required when `isLocalUser` is `false`.                           | 8.2.0 |

### Enums

#### SmartReplySuggestionResultStatus

| Members                    | Value                      | Description                                                                       | Since |
| -------------------------- | -------------------------- | --------------------------------------------------------------------------------- | ----- |
| **`Success`**              | `'SUCCESS'`                | Suggestions were generated successfully.                                          | 8.2.0 |
| **`NotSupportedLanguage`** | `'NOT_SUPPORTED_LANGUAGE'` | No suggestions were generated because the conversation language is not supported. | 8.2.0 |
| **`NoReply`**              | `'NO_REPLY'`               | No suggestions were generated for the conversation.                               | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. The `suggestReplies(...)` method is only available on Android and iOS, so there is no web implementation.

### Which languages are supported?

Smart Reply only supports conversations in English. If the conversation is in another language, the result `status` is `NOT_SUPPORTED_LANGUAGE` and no suggestions are returned.

### Why did I not get any suggestions?

The model may not return suggestions for every conversation, for example when the language is not supported (`NOT_SUPPORTED_LANGUAGE`) or when it cannot generate a suitable reply for the given context (`NO_REPLY`). Always check the `status` and handle the case where `suggestions` is empty.

### How many suggestions are returned?

The model returns up to 3 reply suggestions. It only considers the last 10 messages of the conversation.

### Do I need to provide a `userId` for every message?

You must provide a `userId` for messages sent by remote users (`isLocalUser: false`), as the model uses it to distinguish participants. Messages sent by the local user (`isLocalUser: true`) do not need a `userId`.

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

## Related Plugins

- [Translation](https://capawesome.io/docs/sdks/capacitor/mlkit/translation/): Translate a conversation before generating reply suggestions.
- [Language Identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/): Detect the language of a conversation.
- [GenAI Rewriting](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-rewriting/): Rewrite a generated reply suggestion in a different tone before sending it.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/smart-reply/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/smart-reply/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Subject Segmentation Plugin

Unofficial Capacitor plugin for [ML Kit Subject Segmentation](https://developers.google.com/ml-kit/vision/subject-segmentation).[1](#fn:1)

## Use Cases

The Subject Segmentation plugin is typically used to separate the subject of a picture from its background, for example:

- **Background removal**: Remove or replace the background of a photo, for example for product images or portraits.
- **Photo editing**: Build editing features that combine the segmented image with new backgrounds or effects.
- **Sticker creation**: Turn photos into cutouts or stickers that users can share in chats and posts.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/subject-segmentation` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/subject-segmentation
npx cap sync
```

### Android

#### API level

This plugin requires a minimum API level of 24.

#### Metadata

You need to add the following meta data **in** the `application` tag in your `AndroidManifest.xml`:

```
<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="subject_segment"/>
<!-- To use multiple models: android:value="face,model2,model3" -->
```

## Usage

The following example shows how to segment a subject from the background.

### Segment a subject from the background

Pass the local path of an image file to `processImage(...)` to perform the segmentation. You can optionally scale the image using the `width` and `height` options and adjust the confidence threshold. The result contains the path to the segmented image file along with its width and height:

```
import { SubjectSegmentation } from '@capacitor-mlkit/subject-segmentation';

const processImage = async () => {
  const { path } = await SubjectSegmentation.processImage({
    path: 'path/to/image.jpg',
    confidence: 0.7,
  });
  return path;
};
```

## API

- [`processImage(...)`](#processimage)
- [`isGoogleSubjectSegmentationModuleAvailable()`](#isgooglesubjectsegmentationmoduleavailable)
- [`installGoogleSubjectSegmentationModule()`](#installgooglesubjectsegmentationmodule)
- [`addListener('googleSubjectSegmentationModuleInstallProgress', ...)`](#addlistenergooglesubjectsegmentationmoduleinstallprogress-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Enums](#enums)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Performs segmentation on an input image.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 7.2.0

______________________________________________________________________

### isGoogleSubjectSegmentationModuleAvailable()

```
isGoogleSubjectSegmentationModuleAvailable() => Promise<IsGoogleSubjectSegmentationModuleAvailableResult>
```

Check if the Google Subject Segmentation module is available.

If the Google Subject Segmentation module is not available, you can install it by using `installGoogleSubjectSegmentationModule()`.

Only available on Android.

**Returns:** `Promise<IsGoogleSubjectSegmentationModuleAvailableResult>`

**Since:** 7.2.0

______________________________________________________________________

### installGoogleSubjectSegmentationModule()

```
installGoogleSubjectSegmentationModule() => Promise<void>
```

Install the Google Subject Segmentation module.

**Attention**: This only starts the installation. The `googleSubjectSegmentationModuleInstallProgress` event listener will notify you when the installation is complete.

Only available on Android.

**Since:** 7.2.0

______________________________________________________________________

### addListener('googleSubjectSegmentationModuleInstallProgress', ...)

```
addListener(eventName: 'googleSubjectSegmentationModuleInstallProgress', listenerFunc: (event: GoogleSubjectSegmentationModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>
```

Called when the Google Subject Segmentation module is installed.

Only available on Android.

| Param              | Type                                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| **`eventName`**    | `'googleSubjectSegmentationModuleInstallProgress'`                     |
| **`listenerFunc`** | `(event: GoogleSubjectSegmentationModuleInstallProgressEvent) => void` |

**Returns:** `Promise<PluginListenerHandle>`

**Since:** 7.2.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => Promise<void>
```

Remove all listeners for this plugin.

Only available on Android.

**Since:** 7.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop         | Type     | Description                           | Since |
| ------------ | -------- | ------------------------------------- | ----- |
| **`path`**   | `string` | The path to the segmented image file. | 7.2.0 |
| **`width`**  | `number` | Returns the width of the image file.  | 7.2.0 |
| **`height`** | `number` | Returns the height of the image file. | 7.2.0 |

#### ProcessImageOptions

| Prop             | Type     | Description                                                                               | Default | Since |
| ---------------- | -------- | ----------------------------------------------------------------------------------------- | ------- | ----- |
| **`path`**       | `string` | The local path to the image file.                                                         |         | 7.2.0 |
| **`width`**      | `number` | Scale the image to this width. If no `height` is given, it will respect the aspect ratio. |         | 7.2.0 |
| **`height`**     | `number` | Scale the image to this height. If no `width` is given, it will respect the aspect ratio. |         | 7.2.0 |
| **`confidence`** | `number` | Sets the confidence threshold.                                                            | `0.9`   | 7.2.0 |

#### IsGoogleSubjectSegmentationModuleAvailableResult

| Prop            | Type      | Description                                                         | Since |
| --------------- | --------- | ------------------------------------------------------------------- | ----- |
| **`available`** | `boolean` | Whether or not the Google Subject Segmentation module is available. | 7.2.0 |

#### PluginListenerHandle

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

#### GoogleSubjectSegmentationModuleInstallProgressEvent

| Prop           | Type                                          | Description                                                    | Since |
| -------------- | --------------------------------------------- | -------------------------------------------------------------- | ----- |
| **`state`**    | `GoogleSubjectSegmentationModuleInstallState` | The current state of the installation.                         | 7.2.0 |
| **`progress`** | `number`                                      | The progress of the installation in percent between 0 and 100. | 7.2.0 |

### Enums

#### GoogleSubjectSegmentationModuleInstallState

| Members               | Value | Since |
| --------------------- | ----- | ----- |
| **`UNKNOWN`**         | `0`   | 7.2.0 |
| **`PENDING`**         | `1`   | 7.2.0 |
| **`DOWNLOADING`**     | `2`   | 7.2.0 |
| **`CANCELED`**        | `3`   | 7.2.0 |
| **`COMPLETED`**       | `4`   | 7.2.0 |
| **`FAILED`**          | `5`   | 7.2.0 |
| **`INSTALLING`**      | `6`   | 7.2.0 |
| **`DOWNLOAD_PAUSED`** | `7`   | 7.2.0 |

## FAQ

### What are the requirements to use this plugin on Android?

The plugin requires a minimum Android API level of 24. You also need to add the `com.google.mlkit.vision.DEPENDENCIES` meta data to your `AndroidManifest.xml` as described in the [Installation](#installation) section.

### Why do I need the Google Subject Segmentation module on Android?

On Android, the segmentation is performed by the Google Subject Segmentation module. Use the `isGoogleSubjectSegmentationModuleAvailable()` method to check if the module is available on the device and the `installGoogleSubjectSegmentationModule()` method to install it if it is not.

### How do I know when the module installation is complete?

The `installGoogleSubjectSegmentationModule()` method only starts the installation. Add a listener for the `googleSubjectSegmentationModuleInstallProgress` event to get notified about the current state of the installation and its progress in percent.

### How can I adjust the accuracy of the segmentation?

You can set the confidence threshold using the `confidence` option of the `processImage(...)` method. The default value is `0.9`. Experiment with different values to find the best result for your images.

### How can I scale the image before it is processed?

Use the `width` and `height` options of the `processImage(...)` method to scale the image. If only one of the two values is given, the aspect ratio of the image is respected.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [Selfie Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/selfie-segmentation/): Unofficial Capacitor plugin for ML Kit Selfie Segmentation.
- [Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Unofficial Capacitor plugin for ML Kit Face Detection.
- [Face Mesh Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/): Unofficial Capacitor plugin for ML Kit Face Mesh Detection.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/subject-segmentation/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/subject-segmentation/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Text Recognition Plugin

Unofficial Capacitor plugin for [ML Kit Text Recognition](https://developers.google.com/ml-kit/vision/text-recognition/v2).[1](#fn:1)

## Use Cases

The Text Recognition plugin is typically used whenever an app needs to extract text from an image, for example:

- **Document digitization**: Convert printed documents, receipts, or business cards into machine-readable text.
- **Data entry automation**: Extract text from forms or labels to prefill input fields and reduce manual typing.
- **Accessibility**: Read text found in images aloud to support screen readers and other assistive technologies.
- **Translation pipelines**: Recognize text in an image before passing it on to a translation service.

## Compatibility

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 8.x.x          | >=8.x.x           | Active support |

## Installation

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/text-recognition` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/text-recognition
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### App Size Impact

This plugin bundles a separate model for each supported script (Latin, Chinese, Devanagari, Japanese, and Korean). Each model increases the size of your app by several megabytes. Keep this in mind when deciding which scripts your app actually needs.

### Android

#### Variables

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

- `$mlkitTextRecognitionVersion` version of `com.google.mlkit:text-recognition` (default: `16.0.1`)
- `$mlkitTextRecognitionChineseVersion` version of `com.google.mlkit:text-recognition-chinese` (default: `16.0.1`)
- `$mlkitTextRecognitionDevanagariVersion` version of `com.google.mlkit:text-recognition-devanagari` (default: `16.0.1`)
- `$mlkitTextRecognitionJapaneseVersion` version of `com.google.mlkit:text-recognition-japanese` (default: `16.0.1`)
- `$mlkitTextRecognitionKoreanVersion` version of `com.google.mlkit:text-recognition-korean` (default: `16.0.1`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following example shows how to recognize text in an image.

### Recognize text in an image

Recognize text in an image at a local path. You can select the script of the text to recognize. Only available on Android and iOS:

```
import { Script, TextRecognition } from '@capacitor-mlkit/text-recognition';

const processImage = async () => {
  const { text, blocks } = await TextRecognition.processImage({
    path: 'path/to/image.jpg',
    script: Script.Latin,
  });
  return { text, blocks };
};
```

## API

- [`processImage(...)`](#processimage)
- [Interfaces](#interfaces)
- [Enums](#enums)

### processImage(...)

```
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

Recognizes text in the supplied image.

Only available on Android and iOS.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `ProcessImageOptions` |

**Returns:** `Promise<ProcessImageResult>`

**Since:** 8.2.0

______________________________________________________________________

### Interfaces

#### ProcessImageResult

| Prop         | Type          | Description                    | Since |
| ------------ | ------------- | ------------------------------ | ----- |
| **`text`**   | `string`      | The full recognized text.      | 8.2.0 |
| **`blocks`** | `TextBlock[]` | The recognized blocks of text. | 8.2.0 |

#### TextBlock

Represents a block of text.

A block is a contiguous set of text lines, such as a paragraph or a column.

| Prop                     | Type         | Description                                                                                                     | Since |
| ------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**               | `string`     | The recognized text of the block.                                                                               | 8.2.0 |
| **`boundingBox`**        | `Rect`       | The bounding box of the block.                                                                                  | 8.2.0 |
| **`cornerPoints`**       | `Point[]`    | The four corner points of the block in clockwise order, starting with the top-left point relative to the image. | 8.2.0 |
| **`recognizedLanguage`** | `string`     | The BCP-47 language code of the recognized language of the block.                                               | 8.2.0 |
| **`lines`**              | `TextLine[]` | The recognized lines of text within the block.                                                                  | 8.2.0 |

#### Rect

Represents a rectangle.

| Prop         | Type     | Description                             | Since |
| ------------ | -------- | --------------------------------------- | ----- |
| **`left`**   | `number` | The left coordinate of the rectangle.   | 8.2.0 |
| **`top`**    | `number` | The top coordinate of the rectangle.    | 8.2.0 |
| **`right`**  | `number` | The right coordinate of the rectangle.  | 8.2.0 |
| **`bottom`** | `number` | The bottom coordinate of the rectangle. | 8.2.0 |

#### Point

Represents a point.

| Prop    | Type     | Description                    | Since |
| ------- | -------- | ------------------------------ | ----- |
| **`x`** | `number` | The x coordinate of the point. | 8.2.0 |
| **`y`** | `number` | The y coordinate of the point. | 8.2.0 |

#### TextLine

Represents a line of text.

| Prop                     | Type            | Description                                                                                                    | Since |
| ------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**               | `string`        | The recognized text of the line.                                                                               | 8.2.0 |
| **`boundingBox`**        | `Rect`          | The bounding box of the line.                                                                                  | 8.2.0 |
| **`cornerPoints`**       | `Point[]`       | The four corner points of the line in clockwise order, starting with the top-left point relative to the image. | 8.2.0 |
| **`recognizedLanguage`** | `string`        | The BCP-47 language code of the recognized language of the line.                                               | 8.2.0 |
| **`elements`**           | `TextElement[]` | The recognized elements of text within the line.                                                               | 8.2.0 |

#### TextElement

Represents an element of text.

An element is a contiguous set of characters, such as a word.

| Prop                     | Type      | Description                                                                                                       | Since |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**               | `string`  | The recognized text of the element.                                                                               | 8.2.0 |
| **`boundingBox`**        | `Rect`    | The bounding box of the element.                                                                                  | 8.2.0 |
| **`cornerPoints`**       | `Point[]` | The four corner points of the element in clockwise order, starting with the top-left point relative to the image. | 8.2.0 |
| **`recognizedLanguage`** | `string`  | The BCP-47 language code of the recognized language of the element.                                               | 8.2.0 |

#### ProcessImageOptions

| Prop         | Type     | Description                                                                                              | Default        | Since |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------- | -------------- | ----- |
| **`path`**   | `string` | The local path to the image file.                                                                        |                | 8.2.0 |
| **`script`** | `Script` | The script of the text to recognize. Each script requires a separate model that is bundled with the app. | `Script.Latin` | 8.2.0 |

### Enums

#### Script

| Members          | Value          | Description            | Since |
| ---------------- | -------------- | ---------------------- | ----- |
| **`Latin`**      | `'LATIN'`      | The Latin script.      | 8.2.0 |
| **`Chinese`**    | `'CHINESE'`    | The Chinese script.    | 8.2.0 |
| **`Devanagari`** | `'DEVANAGARI'` | The Devanagari script. | 8.2.0 |
| **`Japanese`**   | `'JAPANESE'`   | The Japanese script.   | 8.2.0 |
| **`Korean`**     | `'KOREAN'`     | The Korean script.     | 8.2.0 |

## FAQ

### Which platforms are supported by this plugin?

The `processImage(...)` method is only available on Android and iOS. The Web platform is not supported by the underlying ML Kit Text Recognition SDK.

### Which scripts are supported?

The plugin supports the Latin, Chinese, Devanagari, Japanese, and Korean scripts. Use the `script` option to select the script of the text you want to recognize. Each script uses a separate model that is bundled with your app.

### Does bundling all scripts increase the app size?

Yes. Each script model adds several megabytes to your app. All five models are bundled so that every script can be used at runtime without an additional download.

### In which format do I have to provide the image path?

The `path` must be a local file path (e.g. `file:///path/to/image.jpg`). Remote URLs are not supported.

### Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

## Related Plugins

- [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes with ML Kit Barcode Scanning.
- [ML Kit Image Labeling](https://capawesome.io/docs/sdks/capacitor/mlkit/image-labeling/): Detect labels in images with ML Kit Image Labeling.
- [ML Kit Face Detection](https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/): Detect faces in images with ML Kit Face Detection.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/text-recognition/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/text-recognition/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Capacitor ML Kit Translation Plugin

Unofficial Capacitor plugin for [ML Kit Translation](https://developers.google.com/ml-kit/language/translation).[1](#fn:1)

## Use Cases

The Translation plugin is typically used to translate text directly on the device, for example:

- **Chat translation**: Translate incoming messages into the language of the user.
- **Content translation**: Let users translate user-generated content such as comments, reviews, or posts.
- **Offline translation**: Download language models in advance so users can translate text without an internet connection.
- **Travel apps**: Help travelers translate text on the go, even when roaming without a data connection.

## 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

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

```
npx skills add capawesome-team/skills --skill capacitor-plugins
```

Then use the following prompt:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/translation` plugin in my project.
```

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

```
npm install @capacitor-mlkit/translation
npx cap sync
```

**Attention**: This plugin **only supports CocoaPods** for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see [this comment](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099).

### Android

#### 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:

- `$mlkitTranslateVersion` version of `com.google.mlkit:translate` (default: `17.0.3`)

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

### iOS

#### Minimum Deployment Target

Make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5`:

```
platform :ios, '15.5'
```

## Configuration

No configuration required for this plugin.

## Demo

A working example can be found here: [robingenz/capacitor-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## Usage

The following examples show how to translate a text, download a language model, list the downloaded language models, and delete a downloaded language model.

### Translate a text

Use the `translate(...)` method to translate a text from a source language to a target language. If the language model for the given languages is not downloaded yet, it will be downloaded automatically, which may take some time. Only available on Android and iOS:

```
import { Translation, Language } from '@capacitor-mlkit/translation';

const translate = async () => {
  const { text } = await Translation.translate({
    text: 'Good morning!',
    sourceLanguage: Language.English,
    targetLanguage: Language.German,
  });
  return text;
};
```

### Download a language model

Download a language model in advance to enable offline translation. Language models are around 30MB in size, so be sure to only download the models you need and only download them using a WiFi connection unless the user has specified otherwise. Only available on Android and iOS:

```
import { Translation, Language } from '@capacitor-mlkit/translation';

const downloadModel = async () => {
  await Translation.downloadModel({
    language: Language.English,
  });
};
```

### List the downloaded language models

Get the languages for which a model has already been downloaded to the device. Only available on Android and iOS:

```
import { Translation } from '@capacitor-mlkit/translation';

const getDownloadedModels = async () => {
  const { languages } = await Translation.getDownloadedModels();
  return languages;
};
```

### Delete a downloaded language model

Delete the language model for a given language, for example to free up storage space on the device. Only available on Android and iOS:

```
import { Translation, Language } from '@capacitor-mlkit/translation';

const deleteDownloadedModel = async () => {
  await Translation.deleteDownloadedModel({
    language: Language.English,
  });
};
```

## API

- [`deleteDownloadedModel(...)`](#deletedownloadedmodel)
- [`downloadModel(...)`](#downloadmodel)
- [`getDownloadedModels()`](#getdownloadedmodels)
- [`translate(...)`](#translate)
- [Interfaces](#interfaces)
- [Enums](#enums)

### deleteDownloadedModel(...)

```
deleteDownloadedModel(options: DeleteDownloadedModelOptions) => Promise<void>
```

Delete the language model for the given language.

Only available on Android and iOS.

| Param         | Type                           |
| ------------- | ------------------------------ |
| **`options`** | `DeleteDownloadedModelOptions` |

**Since:** 0.0.1

______________________________________________________________________

### downloadModel(...)

```
downloadModel(options: DownloadModel) => Promise<void>
```

Download a language model for offline translation.

Language models are around 30MB in size, so be sure to only download the models you need and only download them using a WiFi connection unless the user has specified otherwise.

Only available on Android and iOS.

| Param         | Type            |
| ------------- | --------------- |
| **`options`** | `DownloadModel` |

**Since:** 0.0.1

______________________________________________________________________

### getDownloadedModels()

```
getDownloadedModels() => Promise<GetDownloadedModelsResult>
```

Get the languages for which a model has been downloaded.

Only available on Android and iOS.

**Returns:** `Promise<GetDownloadedModelsResult>`

**Since:** 0.0.1

______________________________________________________________________

### translate(...)

```
translate(options: TranslateOptions) => Promise<TranslateResult>
```

Translate the given text.

If the language model for the given source and target languages is not downloaded, it will be downloaded automatically which may take some time. If you want to avoid this, use the `downloadModel(...)` method to download the model first.

Only available on Android and iOS.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `TranslateOptions` |

**Returns:** `Promise<TranslateResult>`

**Since:** 0.0.1

______________________________________________________________________

### Interfaces

#### DeleteDownloadedModelOptions

| Prop           | Type       | Description                                 | Since |
| -------------- | ---------- | ------------------------------------------- | ----- |
| **`language`** | `Language` | The language for which to delete the model. | 0.0.1 |

#### DownloadModel

| Prop           | Type       | Description                             | Since |
| -------------- | ---------- | --------------------------------------- | ----- |
| **`language`** | `Language` | The language to download the model for. | 0.0.1 |

#### GetDownloadedModelsResult

| Prop            | Type         | Description                                          |
| --------------- | ------------ | ---------------------------------------------------- |
| **`languages`** | `Language[]` | The languages for which a model has been downloaded. |

#### TranslateResult

| Prop       | Type     | Description          | Since |
| ---------- | -------- | -------------------- | ----- |
| **`text`** | `string` | The translated text. | 0.0.1 |

#### TranslateOptions

| Prop                 | Type       | Description                                                                                                                                             | Since |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`text`**           | `string`   | The text to translate.                                                                                                                                  | 0.0.1 |
| **`sourceLanguage`** | `Language` | The source language of the text. If you don't know the source language, you can use the [`Language</a> Identification` plugin to detect it.](#language) | 0.0.1 |
| **`targetLanguage`** | `Language` | The target language to translate the text to.                                                                                                           | 0.0.1 |

### Enums

#### Language

| Members          | Value  | Since |
| ---------------- | ------ | ----- |
| **`Afrikaans`**  | `'af'` | 0.0.1 |
| **`Arabic`**     | `'ar'` | 0.0.1 |
| **`Belarusian`** | `'be'` | 0.0.1 |
| **`Bulgarian`**  | `'bg'` | 0.0.1 |
| **`Bengali`**    | `'bn'` | 0.0.1 |
| **`Catalan`**    | `'ca'` | 0.0.1 |
| **`Czech`**      | `'cs'` | 0.0.1 |
| **`Welsh`**      | `'cy'` | 0.0.1 |
| **`Danish`**     | `'da'` | 0.0.1 |
| **`German`**     | `'de'` | 0.0.1 |
| **`Greek`**      | `'el'` | 0.0.1 |
| **`English`**    | `'en'` | 0.0.1 |
| **`Esperanto`**  | `'eo'` | 0.0.1 |
| **`Spanish`**    | `'es'` | 0.0.1 |
| **`Estonian`**   | `'et'` | 0.0.1 |
| **`Persian`**    | `'fa'` | 0.0.1 |
| **`Finnish`**    | `'fi'` | 0.0.1 |
| **`French`**     | `'fr'` | 0.0.1 |
| **`Irish`**      | `'ga'` | 0.0.1 |
| **`Galician`**   | `'gl'` | 0.0.1 |
| **`Gujarati`**   | `'gu'` | 0.0.1 |
| **`Hebrew`**     | `'he'` | 0.0.1 |
| **`Hindi`**      | `'hi'` | 0.0.1 |
| **`Croatian`**   | `'hr'` | 0.0.1 |
| **`Haitian`**    | `'ht'` | 0.0.1 |
| **`Hungarian`**  | `'hu'` | 0.0.1 |
| **`Indonesian`** | `'id'` | 0.0.1 |
| **`Icelandic`**  | `'is'` | 0.0.1 |
| **`Italian`**    | `'it'` | 0.0.1 |
| **`Japanese`**   | `'ja'` | 0.0.1 |
| **`Georgian`**   | `'ka'` | 0.0.1 |
| **`Kannada`**    | `'kn'` | 0.0.1 |
| **`Korean`**     | `'ko'` | 0.0.1 |
| **`Lithuanian`** | `'lt'` | 0.0.1 |
| **`Latvian`**    | `'lv'` | 0.0.1 |
| **`Macedonian`** | `'mk'` | 0.0.1 |
| **`Marathi`**    | `'mr'` | 0.0.1 |
| **`Malay`**      | `'ms'` | 0.0.1 |
| **`Maltese`**    | `'mt'` | 0.0.1 |
| **`Dutch`**      | `'nl'` | 0.0.1 |
| **`Norwegian`**  | `'no'` | 0.0.1 |
| **`Polish`**     | `'pl'` | 0.0.1 |
| **`Portuguese`** | `'pt'` | 0.0.1 |
| **`Romanian`**   | `'ro'` | 0.0.1 |
| **`Russian`**    | `'ru'` | 0.0.1 |
| **`Slovak`**     | `'sk'` | 0.0.1 |
| **`Slovenian`**  | `'sl'` | 0.0.1 |
| **`Albanian`**   | `'sq'` | 0.0.1 |
| **`Swedish`**    | `'sv'` | 0.0.1 |
| **`Swahili`**    | `'sw'` | 0.0.1 |
| **`Tamil`**      | `'ta'` | 0.0.1 |
| **`Telugu`**     | `'te'` | 0.0.1 |
| **`Thai`**       | `'th'` | 0.0.1 |
| **`Tagalog`**    | `'tl'` | 0.0.1 |
| **`Turkish`**    | `'tr'` | 0.0.1 |
| **`Ukrainian`**  | `'uk'` | 0.0.1 |
| **`Urdu`**       | `'ur'` | 0.0.1 |
| **`Vietnamese`** | `'vi'` | 0.0.1 |
| **`Chinese`**    | `'zh'` | 0.0.1 |

## FAQ

### Which platforms are supported by this plugin?

The plugin is available on Android and iOS. All methods are only available on Android and iOS, so there is no web implementation.

### Which languages are supported?

The plugin supports more than 50 languages, including English, German, Spanish, French, Chinese, and Japanese. See the `Language` enum in the [API](#api) section for the complete list.

### Does the translation work offline?

Yes, the translation is performed on the device using downloaded language models. Use the `downloadModel(...)` method to download a language model in advance, for example while the device is connected to a WiFi network. Otherwise, the model is downloaded automatically on the first call to `translate(...)`, which may take some time.

### How much storage do the language models require?

Language models are around 30MB in size, so be sure to only download the models you need. You can delete a model that is no longer needed using the `deleteDownloadedModel(...)` method.

### What if I don't know the source language of the text?

The `translate(...)` method requires a source language. You can use the ML Kit Language Identification plugin to detect the language of a text before translating it.

### Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your `ios/App/Podfile` to at least `15.5` (see [Installation](#installation)).

## Related Plugins

- [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/): Transcribe speech into text, for example to translate it afterwards.
- [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text, for example to read translated text aloud.
- [App Language](https://capawesome.io/docs/sdks/capacitor/app-language/): Manage the app's own language override, independent of the device language.
- [ML Kit Entity Extraction](https://capawesome.io/docs/sdks/capacitor/mlkit/entity-extraction/): Extract entities such as addresses and dates from text before or after translating it.

## Terms & Privacy

This plugin uses the [Google ML Kit](https://developers.google.com/ml-kit):

- [Terms & Privacy](https://developers.google.com/ml-kit/terms)
- [Android Data Disclosure](https://developers.google.com/ml-kit/android-data-disclosure)
- [iOS Data Disclosure](https://developers.google.com/ml-kit/ios-data-disclosure)

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/translation/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/translation/LICENSE).

______________________________________________________________________

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Cordova Plugins

Cordova plugins let you access native device features and third-party SDKs from your Apache Cordova app through a single JavaScript API that works across Android and iOS.

This page lists our Cordova plugins. Open a plugin's page for installation steps, supported platforms, and the full API reference.

## Plugins

- [Live Update](https://capawesome.io/docs/sdks/cordova/live-update/index.md) — Ship over-the-air updates with auto-update and rollback.

## FAQ

### What are Cordova plugins?

Cordova plugins are packages that expose native Android and iOS functionality through a unified JavaScript API. They let you call platform features from the same codebase, without writing native code yourself. To learn more about the underlying framework, see the [official Apache Cordova documentation](https://cordova.apache.org/docs/en/latest/).

### Are these Cordova plugins free?

Most plugins are open source and free to use, while a few are offered as paid plugins through [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md). Licensing and pricing are documented on each plugin's page.

### Which platforms do the plugins support?

The plugins support Android and iOS. The supported platforms are listed at the top of each plugin's documentation page.

### How do I get support?

For bugs and feature requests, open an issue on the plugin's GitHub repository. For dedicated help, see our [support options](/docs/support/).

## Next steps

- Explore [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) for Live Updates, Native Builds, and App Store Publishing.
- Browse our [Capacitor plugins](https://capawesome.io/docs/sdks/capacitor/index.md).
- View the source on [GitHub](https://github.com/capawesome-team).
- Need help choosing or integrating a plugin? See our [support options](/docs/support/).

# Cordova Live Update Plugin

Cordova plugin that allows you to update your app remotely in real-time without requiring users to download a new version from the app store, also known as Over-the-Air (OTA) updates.

## Features

- 🔋 Supports **Android and iOS**
- ⚡️ Works with **stock Cordova WebView** — does **not** require `cordova-plugin-ionic-webview`
- 📦 **Bundle Management** — download, set, and delete bundles
- ☁️ **Cloud Support** — manage updates via [Capawesome Cloud](https://cloud.capawesome.io/)
- 📺 **Channel Support** — set a channel for the app to manage different versions
- 🔄 **Auto Update** — background update strategy with 15-minute throttle
- 🛟 **Rollback** — automatic revert to the default bundle on failed updates
- 🔁 **Delta Updates** — manifest mode downloads only changed files
- ⚙️ **Runtime Configuration** — update plugin configuration at runtime
- 📡 **Update Lifecycle Events** — track download progress, react to bundle changes, detect reloads
- 🏷️ **Custom Properties** — associate custom key-value metadata with bundles via Capawesome Cloud
- 🔒 **Security** — verify authenticity and integrity of bundles via RSA signature
- 🌐 **Open Source** — MIT licensed

## Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Compatibility

| Plugin Version | Cordova Android Version | Cordova iOS Version | Status         |
| -------------- | ----------------------- | ------------------- | -------------- |
| 0.1.x          | >=13.0.0                | >=7.0.0             | Active support |

## WebView Compatibility

This plugin swaps the files served to the WebView by hooking into Cordova's official plugin extension points (`CordovaPluginPathHandler` on Android, `CDVPluginSchemeHandler` on iOS). These hooks only fire when the WebView loads content via a custom scheme, which is the **default** for modern Cordova:

- **Android** (cordova-android ≥10): loads from `https://localhost/` via `WebViewAssetLoader`.
- **iOS** (cordova-ios ≥7): loads from `app://localhost/` via `WKURLSchemeHandler`.

The plugin does **NOT** work if your app forces the WebView back to the legacy `file://` scheme, for example:

- `<preference name="AndroidInsecureFileModeEnabled" value="true" />`
- `<preference name="Scheme" value="file" />`

### cordova-plugin-ionic-webview

[`cordova-plugin-ionic-webview`](https://github.com/ionic-team/cordova-plugin-ionic-webview) is **not compatible** with this plugin. It replaces the WebView with its own local server that serves content directly and never calls the extension points above, so downloaded bundles are silently ignored — `sync()` and `reload()` appear to succeed, but the WebView keeps showing the content shipped in the app binary. This affects both Android and iOS.

If your app uses `cordova-plugin-ionic-webview`, remove it:

```
cordova plugin remove cordova-plugin-ionic-webview
```

It is no longer maintained and is no longer needed: modern Cordova serves the WebView through WKWebView on iOS and the system WebView on Android out of the box, with the same custom-scheme behavior this plugin relies on.

## Guides

- [Getting Started with Capawesome Cloud Live Updates](https://capawesome.io/cloud/live-updates/setup/)
- [Migrating from Ionic Appflow to Capawesome Cloud](https://capawesome.io/blog/migrating-from-ionic-appflow-to-capawesome-cloud/)

## Installation

Install the plugin by running the following command and follow the platform-specific instructions below:

```
cordova plugin add @capawesome/cordova-live-update --variable APP_ID=<your-app-id>
```

### Android

#### Channel

For a **static** default channel, use the [`DEFAULT_CHANNEL`](#plugin-variables) plugin variable — no native config required.

If you are using [Versioned Channels](https://capawesome.io/cloud/live-updates/guides/best-practices/#versioned-channels), the channel value needs to be interpolated from the build's `versionCode`, which can't be expressed via a plugin variable. Use Cordova's `build-extras.gradle` mechanism instead. In your app's `config.xml`, add:

```
<platform name="android">
    <resource-file src="build-extras.gradle" target="app/build-extras.gradle"/>
</platform>
```

Then create `build-extras.gradle` next to `config.xml`:

```
android {
    applicationVariants.all { variant ->
        variant.resValue "string", "capawesome_live_update_default_channel", "production-${variant.versionCode}"
    }
}
```

### iOS

#### Channel

For a **static** default channel, use the [`DEFAULT_CHANNEL`](#plugin-variables) plugin variable — no native config required.

If you are using [Versioned Channels](https://capawesome.io/cloud/live-updates/guides/best-practices/#versioned-channels), use Cordova's `<config-file>` mechanism in your app's `config.xml`:

```
<platform name="ios">
    <config-file target="*-Info.plist" parent="CapawesomeLiveUpdateDefaultChannel">
        <string>production-$(CURRENT_PROJECT_VERSION)</string>
    </config-file>
</platform>
```

Xcode resolves `$(CURRENT_PROJECT_VERSION)` at build time.

#### Privacy manifest

Starting with [cordova-ios 7.1.0](https://cordova.apache.org/announcements/2024/04/03/cordova-ios-7.1.0.html), the iOS [Privacy Manifest](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) is configured via a `<privacy-manifest>` element inside the `<platform name="ios">` section of your app's `config.xml`. Add an `NSPrivacyAccessedAPICategoryUserDefaults` entry for this plugin:

```
<platform name="ios">
    <privacy-manifest>
        <key>NSPrivacyAccessedAPITypes</key>
        <array>
            <!-- Add this dict entry to the array if the key already exists. -->
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>CA92.1</string>
                </array>
            </dict>
        </array>
    </privacy-manifest>
</platform>
```

We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278401) as the reason for accessing the [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults) API.

## Plugin Variables

These map to Cordova `<preference>` entries in `config.xml`. Set them at install time with `--variable`, or edit `config.xml` directly:

| Variable                         | Default                   | Description                                                                                                            |
| -------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `APP_ID`                         | *(empty)*                 | Capawesome Cloud app ID (a UUID).                                                                                      |
| `DEFAULT_CHANNEL`                | *(empty)*                 | Default channel name. Overridden by native config or `setChannel()`.                                                   |
| `AUTO_UPDATE_STRATEGY`           | `none`                    | `none` or `background`. `background` runs `sync()` on cold start and foreground (15-minute throttle).                  |
| `HTTP_TIMEOUT`                   | `60000`                   | HTTP request timeout in milliseconds.                                                                                  |
| `PUBLIC_KEY`                     | *(empty)*                 | PEM-encoded RSA public key for signature verification. When set, all bundle downloads must include a valid signature.  |
| `READY_TIMEOUT`                  | `0`                       | Milliseconds to wait for `ready()` before automatic rollback. Set to e.g. `10000` to enable rollback. `0` disables it. |
| `SERVER_DOMAIN`                  | `api.cloud.capawesome.io` | Capawesome Cloud API host (no scheme/path).                                                                            |
| `AUTO_DELETE_BUNDLES`            | `false`                   | Whether to delete unused bundles when `ready()` is called.                                                             |
| `AUTO_BLOCK_ROLLED_BACK_BUNDLES` | `false`                   | Whether to block bundles that caused a rollback. No effect if `READY_TIMEOUT=0`.                                       |

### Example

```
<plugin name="@capawesome/cordova-live-update" spec="0.1.0">
  <variable name="APP_ID" value="6e351b4f-69a7-415e-a057-4567df7ffe94" />
  <variable name="AUTO_UPDATE_STRATEGY" value="background" />
  <variable name="DEFAULT_CHANNEL" value="production" />
  <variable name="READY_TIMEOUT" value="10000" />
  <variable name="PUBLIC_KEY" value="-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDodf1SD0OOn6hIlDuKBza0Ed0OqtwyVJwiyjmE9BJaZ7y8ZUfcF+SKmd0l2cDPM45XIg2tAFux5n29uoKyHwSt+6tCi5CJA5Z1/1eZruRRqABLonV77KS3HUtvOgqRLDnKSV89dYZkM++NwmzOPgIF422mvc+VukcVOBfc8/AHQIDAQAB-----END PUBLIC KEY-----" />
</plugin>
```

## Demo

A working example can be found here: [capawesome-team/cordova-live-update-demo](https://github.com/capawesome-team/cordova-live-update-demo)

| Android | iOS |
| ------- | --- |
|         |     |

## Usage

The plugin attaches to `cordova.plugins.LiveUpdate` once `deviceready` fires.

If you use TypeScript, type definitions are available from the npm package:

```
import type { LiveUpdatePlugin } from '@capawesome/cordova-live-update';

declare const cordova: { plugins: { LiveUpdate: LiveUpdatePlugin } };
```

```
const { LiveUpdate } = cordova.plugins;

const deleteBundle = async () => {
  await LiveUpdate.deleteBundle({ bundleId: 'my-bundle' });
};

const downloadBundle = async () => {
  await LiveUpdate.downloadBundle({ url: 'https://example.com/1.0.0.zip', bundleId: '1.0.0' });
};

const fetchChannels = async () => {
  const result = await LiveUpdate.fetchChannels();
  return result.channels;
};

const fetchLatestBundle = async () => {
  await LiveUpdate.fetchLatestBundle();
};

const getBundles = async () => {
  const result = await LiveUpdate.getBundles();
  return result.bundleIds;
};

const getChannel = async () => {
  const result = await LiveUpdate.getChannel();
  return result.channel;
};

const getCurrentBundle = async () => {
  const result = await LiveUpdate.getCurrentBundle();
  return result.bundleId;
};

const getCustomId = async () => {
  const result = await LiveUpdate.getCustomId();
  return result.customId;
};

const getDeviceId = async () => {
  const result = await LiveUpdate.getDeviceId();
  return result.deviceId;
};

const getNextBundle = async () => {
  const result = await LiveUpdate.getNextBundle();
  return result.bundleId;
};

const getVersionCode = async () => {
  const result = await LiveUpdate.getVersionCode();
  return result.versionCode;
};

const getVersionName = async () => {
  const result = await LiveUpdate.getVersionName();
  return result.versionName;
};

const ready = async () => {
  const result = await LiveUpdate.ready();
  if (result.currentBundleId) {
    console.log(`The app is now using the bundle with the identifier ${result.currentBundleId}.`);
  }
  if (result.previousBundleId) {
    console.log(`The app was using the bundle with the identifier ${result.previousBundleId}.`);
  }
  if (result.rollback) {
    console.log('The app was reset to the default bundle.');
  }
};

const reload = async () => {
  await LiveUpdate.reload();
};

const reset = async () => {
  await LiveUpdate.reset();
};

const setChannel = async () => {
  await LiveUpdate.setChannel({ channel: 'production-5' });
};

const setCustomId = async () => {
  await LiveUpdate.setCustomId({ customId: 'my-custom-id' });
};

const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({ bundleId: '7f0b9bf2-dff6-4be2-bcac-b068cc5ea756' });
};

const sync = async () => {
  const result = await LiveUpdate.sync({
    channel: 'production-5',
  });
  return result.nextBundleId;
};

const isNewBundleAvailable = async () => {
  const { bundleId: latestBundleId } = await LiveUpdate.fetchLatestBundle({
    channel: 'production-5',
  });
  if (latestBundleId) {
    const { bundleId: currentBundleId } = await LiveUpdate.getCurrentBundle();
    return latestBundleId !== currentBundleId;
  } else {
    return false;
  }
};
```

## API

- [`clearBlockedBundles()`](#clearblockedbundles)
- [`deleteBundle(...)`](#deletebundle)
- [`downloadBundle(...)`](#downloadbundle)
- [`fetchChannels(...)`](#fetchchannels)
- [`fetchLatestBundle(...)`](#fetchlatestbundle)
- [`getBlockedBundles()`](#getblockedbundles)
- [`getBundles()`](#getbundles)
- [`getChannel()`](#getchannel)
- [`getConfig()`](#getconfig)
- [`getDownloadedBundles()`](#getdownloadedbundles)
- [`getCurrentBundle()`](#getcurrentbundle)
- [`getCustomId()`](#getcustomid)
- [`getDeviceId()`](#getdeviceid)
- [`isSyncing()`](#issyncing)
- [`getNextBundle()`](#getnextbundle)
- [`getVersionCode()`](#getversioncode)
- [`getVersionName()`](#getversionname)
- [`ready()`](#ready)
- [`reload()`](#reload)
- [`reset()`](#reset)
- [`resetConfig()`](#resetconfig)
- [`setChannel(...)`](#setchannel)
- [`setConfig(...)`](#setconfig)
- [`setCustomId(...)`](#setcustomid)
- [`setNextBundle(...)`](#setnextbundle)
- [`sync(...)`](#sync)
- [`addListener('downloadBundleProgress', ...)`](#addlistenerdownloadbundleprogress-)
- [`addListener('nextBundleSet', ...)`](#addlistenernextbundleset-)
- [`removeAllListeners()`](#removealllisteners)
- [Interfaces](#interfaces)
- [Type Aliases](#type-aliases)

### clearBlockedBundles()

```
clearBlockedBundles() => any
```

Clear all blocked bundles from the blocked list.

This removes all bundle identifiers that were automatically blocked due to rollbacks when `autoBlockRolledBackBundles` is enabled.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### deleteBundle(...)

```
deleteBundle(options: DeleteBundleOptions) => any
```

Delete a bundle from the app.

| Param         | Type                  |
| ------------- | --------------------- |
| **`options`** | `DeleteBundleOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### downloadBundle(...)

```
downloadBundle(options: DownloadBundleOptions) => any
```

Download a bundle.

| Param         | Type                    |
| ------------- | ----------------------- |
| **`options`** | `DownloadBundleOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### fetchChannels(...)

```
fetchChannels(options?: FetchChannelsOptions | undefined) => any
```

Fetch channels from [Capawesome Cloud](https://capawesome.io/cloud/).

This is primarily intended for development and QA purposes. It allows you to retrieve a list of available channels so you can dynamically switch between them using `setChannel(...)`.

**Attention**: Only works for apps with public channels enabled. If channels are private, they can still be set using `setChannel(...)` but won't be returned by this method.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `FetchChannelsOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### fetchLatestBundle(...)

```
fetchLatestBundle(options?: FetchLatestBundleOptions | undefined) => any
```

Fetch the latest bundle using the [Capawesome Cloud](https://capawesome.io/cloud/).

| Param         | Type                       |
| ------------- | -------------------------- |
| **`options`** | `FetchLatestBundleOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getBlockedBundles()

```
getBlockedBundles() => any
```

Get all blocked bundle identifiers.

Returns the list of bundle identifiers that were automatically blocked due to rollbacks when `autoBlockRolledBackBundles` is enabled.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getBundles()

```
getBundles() => any
```

Get all identifiers of bundles that have been downloaded.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getChannel()

```
getChannel() => any
```

Get the channel that is used for the update.

The channel is resolved in the following order (highest priority first):

1. `setChannel()` (SharedPreferences on Android / UserDefaults on iOS)
1. Native config (`CapawesomeLiveUpdateDefaultChannel` in `Info.plist` on iOS or `capawesome_live_update_default_channel` in `strings.xml` on Android)
1. The `DEFAULT_CHANNEL` preference in `config.xml`

**Note**: The `channel` parameter of `sync()` takes the highest priority but is not persisted and therefore not returned by this method.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getConfig()

```
getConfig() => any
```

Get the runtime configuration.

Returns the current plugin configuration including any runtime overrides set via `setConfig()`.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getDownloadedBundles()

```
getDownloadedBundles() => any
```

Get all identifiers of bundles that have been downloaded.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getCurrentBundle()

```
getCurrentBundle() => any
```

Get the bundle identifier of the current bundle. The current bundle is the bundle that is currently used by the app.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getCustomId()

```
getCustomId() => any
```

Get the custom identifier of the device.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getDeviceId()

```
getDeviceId() => any
```

Get the unique device identifier.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### isSyncing()

```
isSyncing() => any
```

Check whether a sync operation is currently in progress.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getNextBundle()

```
getNextBundle() => any
```

Get the bundle identifier of the next bundle. The next bundle is the bundle that will be used after calling `reload()` or restarting the app.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getVersionCode()

```
getVersionCode() => any
```

Get the version code of the app.

On **Android**, this is the `versionCode` from `PackageInfo`. On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### getVersionName()

```
getVersionName() => any
```

Get the version name of the app.

On **Android**, this is the `versionName` from `PackageInfo`. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### ready()

```
ready() => any
```

Notify the plugin that the app is ready to use and no rollback is needed.

**Attention**: This method should be called as soon as the app is ready to use to prevent the app from being reset to the default bundle.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### reload()

```
reload() => any
```

Reload the app to apply the new bundle.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### reset()

```
reset() => any
```

Reset the app to the default bundle.

Call `reload()` or restart the app to apply the changes.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### resetConfig()

```
resetConfig() => any
```

Reset the runtime configuration to the values from `config.xml`.

This clears any runtime configuration set via `setConfig()`. The changes take effect immediately.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### setChannel(...)

```
setChannel(options: SetChannelOptions) => any
```

Set the channel to use for the update.

| Param         | Type                |
| ------------- | ------------------- |
| **`options`** | `SetChannelOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### setConfig(...)

```
setConfig(options: SetConfigOptions) => any
```

Set the runtime configuration.

This allows updating plugin configuration options at runtime. The changes are persisted across app restarts and take effect immediately.

**Important:** Runtime configuration is automatically reset to default values whenever the native app is updated to a new version. This ensures that configuration from previous versions doesn't persist after an app update.

| Param         | Type               |
| ------------- | ------------------ |
| **`options`** | `SetConfigOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### setCustomId(...)

```
setCustomId(options: SetCustomIdOptions) => any
```

Set the custom identifier of the device.

| Param         | Type                 |
| ------------- | -------------------- |
| **`options`** | `SetCustomIdOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### setNextBundle(...)

```
setNextBundle(options: SetNextBundleOptions) => any
```

Set the next bundle to use for the app.

Call `reload()` or restart the app to apply the changes.

| Param         | Type                   |
| ------------- | ---------------------- |
| **`options`** | `SetNextBundleOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### sync(...)

```
sync(options?: SyncOptions | undefined) => any
```

Automatically download and set the latest bundle for the app using the [Capawesome Cloud](https://capawesome.io/cloud/).

Call `reload()` or restart the app to apply the changes.

| Param         | Type          |
| ------------- | ------------- |
| **`options`** | `SyncOptions` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### addListener('downloadBundleProgress', ...)

```
addListener(eventName: 'downloadBundleProgress', listenerFunc: DownloadBundleProgressListener) => any
```

Listen for the download progress of a bundle.

| Param              | Type                             |
| ------------------ | -------------------------------- |
| **`eventName`**    | `'downloadBundleProgress'`       |
| **`listenerFunc`** | `DownloadBundleProgressListener` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### addListener('nextBundleSet', ...)

```
addListener(eventName: 'nextBundleSet', listenerFunc: NextBundleSetListener) => any
```

Listen for when a bundle is set as the next bundle.

This event is triggered whenever a bundle is set to be used on the next app restart, either through automatic updates or manual calls to `setNextBundle()`.

| Param              | Type                    |
| ------------------ | ----------------------- |
| **`eventName`**    | `'nextBundleSet'`       |
| **`listenerFunc`** | `NextBundleSetListener` |

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### removeAllListeners()

```
removeAllListeners() => any
```

Remove all listeners for this plugin.

**Returns:** `any`

**Since:** 0.1.0

______________________________________________________________________

### Interfaces

#### DeleteBundleOptions

| Prop           | Type     | Description                                    | Since |
| -------------- | -------- | ---------------------------------------------- | ----- |
| **`bundleId`** | `string` | The unique identifier of the bundle to delete. | 0.1.0 |

#### DownloadBundleOptions

| Prop               | Type         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Default                          | Since   |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------- |
| **`artifactType`** | \`'manifest' | 'zip'\`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The artifact type of the bundle. | `'zip'` |
| **`bundleId`**     | `string`     | The unique identifier of the bundle. **Attention**: The value `public` is reserved and cannot be used as a bundle identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                  | 0.1.0   |
| **`checksum`**     | `string`     | The checksum of the self-hosted bundle as a SHA-256 hash in hex format to verify the integrity of the bundle. **Attention**: Only supported for the `zip` artifact type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                  | 0.1.0   |
| **`signature`**    | `string`     | The signature of the self-hosted bundle as a signed SHA-256 hash in base64 format to verify the integrity of the bundle. **Attention**: Only supported for the `zip` artifact type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                  | 0.1.0   |
| **`url`**          | `string`     | The URL of the bundle to download. For the `zip` artifact type, the URL must point to a ZIP file. For the `manifest` artifact type, the URL serves as the base URL to download the individual files. For example, if the URL is `https://example.com/download`, the plugin will download the file with the href `index.html` from `https://example.com/download?href=index.html`. To **verify the integrity** of the file, the server should return a `X-Checksum` header with the SHA-256 hash in hex format. To **verify the signature** of the file, the server should return a `X-Signature` header with the signed SHA-256 hash in base64 format. |                                  | 0.1.0   |

#### FetchChannelsOptions

| Prop         | Type     | Description                               | Default | Since |
| ------------ | -------- | ----------------------------------------- | ------- | ----- |
| **`limit`**  | `number` | The maximum number of channels to return. | `50`    | 0.1.0 |
| **`offset`** | `number` | The number of channels to skip.           | `0`     | 0.1.0 |
| **`query`**  | `string` | The query to filter channels by name.     |         | 0.1.0 |

#### FetchChannelsResult

| Prop           | Type | Description           | Since |
| -------------- | ---- | --------------------- | ----- |
| **`channels`** | `{}` | The list of channels. | 0.1.0 |

#### Channel

| Prop       | Type     | Description                           | Since |
| ---------- | -------- | ------------------------------------- | ----- |
| **`id`**   | `string` | The unique identifier of the channel. | 0.1.0 |
| **`name`** | `string` | The name of the channel.              | 0.1.0 |

#### FetchLatestBundleOptions

| Prop          | Type     | Description                                                      | Since |
| ------------- | -------- | ---------------------------------------------------------------- | ----- |
| **`channel`** | `string` | The name of the channel where the latest bundle is fetched from. | 0.1.0 |

#### FetchLatestBundleResult

| Prop                   | Type                         | Description                                                                                                                                                                                  | Since                                                                                                                                         |
| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **`artifactType`**     | \`'manifest'                 | 'zip'\`                                                                                                                                                                                      | The artifact type of the bundle.                                                                                                              |
| **`bundleId`**         | \`string                     | null\`                                                                                                                                                                                       | The unique identifier of the latest bundle. On Capawesome Cloud, this is the ID of the app build artifact. If `null`, no bundle is available. |
| **`checksum`**         | `string`                     | The checksum of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the checksum will be returned as response header when downloading the bundle.   | 0.1.0                                                                                                                                         |
| **`customProperties`** | `{ [key: string]: string; }` | Custom properties that are associated with the latest bundle.                                                                                                                                | 0.1.0                                                                                                                                         |
| **`downloadUrl`**      | `string`                     | The URL of the latest bundle to download. Pass this URL to the `downloadBundle(...)` method to download the bundle.                                                                          | 0.1.0                                                                                                                                         |
| **`signature`**        | `string`                     | The signature of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the signature will be returned as response header when downloading the bundle. | 0.1.0                                                                                                                                         |

#### GetBlockedBundlesResult

| Prop            | Type | Description                                            | Since |
| --------------- | ---- | ------------------------------------------------------ | ----- |
| **`bundleIds`** | `{}` | An array of unique identifiers of all blocked bundles. | 0.1.0 |

#### GetBundlesResult

| Prop            | Type | Description                                              | Since |
| --------------- | ---- | -------------------------------------------------------- | ----- |
| **`bundleIds`** | `{}` | An array of unique identifiers of all available bundles. | 0.1.0 |

#### GetChannelResult

| Prop          | Type     | Description | Since                                                              |
| ------------- | -------- | ----------- | ------------------------------------------------------------------ |
| **`channel`** | \`string | null\`      | The channel name. If `null`, the app is using the default channel. |

#### GetConfigResult

| Prop                     | Type     | Description    | Since                                                                    |
| ------------------------ | -------- | -------------- | ------------------------------------------------------------------------ |
| **`appId`**              | \`string | null\`         | The app ID used to identify the app. If `null`, no app ID is configured. |
| **`autoUpdateStrategy`** | \`'none' | 'background'\` | The auto-update strategy for live updates.                               |

#### GetDownloadedBundlesResult

| Prop            | Type | Description                                               | Since |
| --------------- | ---- | --------------------------------------------------------- | ----- |
| **`bundleIds`** | `{}` | An array of unique identifiers of all downloaded bundles. | 0.1.0 |

#### GetCurrentBundleResult

| Prop           | Type     | Description | Since                                                                                     |
| -------------- | -------- | ----------- | ----------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the current bundle. If `null`, the default bundle is being used. |

#### GetCustomIdResult

| Prop           | Type     | Description | Since                                                                        |
| -------------- | -------- | ----------- | ---------------------------------------------------------------------------- |
| **`customId`** | \`string | null\`      | The custom identifier of the device. If `null`, no custom identifier is set. |

#### GetDeviceIdResult

| Prop           | Type     | Description                                                                                                                                                                                                                                                                    | Since |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`deviceId`** | `string` | The unique identifier of the device. On iOS, [`identifierForVendor`](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) is used. The value of this property is the same for apps that come from the same vendor running on the same device. | 0.1.0 |

#### IsSyncingResult

| Prop          | Type      | Description                                        | Since |
| ------------- | --------- | -------------------------------------------------- | ----- |
| **`syncing`** | `boolean` | Whether a sync operation is currently in progress. | 0.1.0 |

#### GetNextBundleResult

| Prop           | Type     | Description | Since                                                                                  |
| -------------- | -------- | ----------- | -------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the next bundle. If `null`, the default bundle is being used. |

#### GetVersionCodeResult

| Prop              | Type     | Description                                                                                                                                                      | Since |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`versionCode`** | `string` | The version code of the app. On **Android**, this is the `versionCode` from `PackageInfo`. On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file. | 0.1.0 |

#### GetVersionNameResult

| Prop              | Type     | Description                                                                                                                                                                 | Since |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`versionName`** | `string` | The version name of the app. On **Android**, this is the `versionName` from `PackageInfo`. On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file. | 0.1.0 |

#### ReadyResult

| Prop                   | Type      | Description                                             | Since                                                                                   |
| ---------------------- | --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **`previousBundleId`** | \`string  | null\`                                                  | The identifier of the previous bundle used. If `null`, the default bundle was used.     |
| **`currentBundleId`**  | \`string  | null\`                                                  | The identifier of the current bundle used. If `null`, the default bundle is being used. |
| **`rollback`**         | `boolean` | Whether or not the app was reset to the default bundle. | 0.1.0                                                                                   |

#### SetChannelOptions

| Prop          | Type     | Description | Since                                               |
| ------------- | -------- | ----------- | --------------------------------------------------- |
| **`channel`** | \`string | null\`      | The channel name. Set `null` to remove the channel. |

#### SetConfigOptions

| Prop        | Type     | Description | Since                                                                                                               |
| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| **`appId`** | \`string | null\`      | The app ID used to identify the app. Set `null` to reset to the value from the `APP_ID` preference in `config.xml`. |

#### SetCustomIdOptions

| Prop           | Type     | Description | Since                                                                            |
| -------------- | -------- | ----------- | -------------------------------------------------------------------------------- |
| **`customId`** | \`string | null\`      | The custom identifier of the device. Set `null` to remove the custom identifier. |

#### SetNextBundleOptions

| Prop           | Type     | Description | Since                                                                                                         |
| -------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the bundle to use. Set `null` to use the default bundle (same as calling `reset()`). |

#### SyncOptions

| Prop          | Type     | Description                                                      | Since |
| ------------- | -------- | ---------------------------------------------------------------- | ----- |
| **`channel`** | `string` | The name of the channel where the latest bundle is fetched from. | 0.1.0 |

#### SyncResult

| Prop               | Type     | Description | Since                                                                                                      |
| ------------------ | -------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| **`nextBundleId`** | \`string | null\`      | The identifier of the next bundle to use. If `null`, the app is up-to-date and no new bundle is available. |

#### DownloadBundleProgressEvent

Event that is triggered when the download progress of a bundle changes.

| Prop                  | Type     | Description                                                             | Since |
| --------------------- | -------- | ----------------------------------------------------------------------- | ----- |
| **`bundleId`**        | `string` | The unique identifier of the bundle that is being downloaded.           | 0.1.0 |
| **`downloadedBytes`** | `number` | The number of bytes that have been downloaded.                          | 0.1.0 |
| **`progress`**        | `number` | The progress of the download in percent as a value between `0` and `1`. | 0.1.0 |
| **`totalBytes`**      | `number` | The total number of bytes to download.                                  | 0.1.0 |

#### PluginListenerHandle

Handle returned from `addListener(...)`. Call `remove()` to detach the listener.

| Prop         | Type        |
| ------------ | ----------- |
| **`remove`** | `() => any` |

#### NextBundleSetEvent

Event that is triggered when a bundle is set as the next bundle.

| Prop           | Type     | Description | Since                                                                                                           |
| -------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| **`bundleId`** | \`string | null\`      | The unique identifier of the bundle that is set as the next bundle. If `null`, the default bundle will be used. |

### Type Aliases

#### DownloadBundleProgressListener

Listener for the download progress of a bundle.

`(event: DownloadBundleProgressEvent): void`

#### NextBundleSetListener

Listener for when a bundle is set as the next bundle.

`(event: NextBundleSetEvent): void`

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/cordova-live-update/blob/main/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/cordova-live-update/blob/main/LICENSE).
# Cloud

# Capawesome Cloud

Capawesome Cloud is a mobile DevOps platform for building, updating, and shipping your iOS and Android apps. New to it? Start with [Getting Started](https://capawesome.io/docs/cloud/getting-started/index.md). Curious how teams use it? Explore [solutions by use case](https://capawesome.io/solutions/) — white-label apps, beta testing, hotfixes, and more.

## Products

- **[Live Updates](https://capawesome.io/docs/cloud/live-updates/index.md)** — ship over-the-air updates to your app's web layer in minutes, without an app store review.
- **[Native Builds](https://capawesome.io/docs/cloud/native-builds/index.md)** — build native iOS and Android apps in the cloud, no Mac required.
- **[App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md)** — submit builds straight to TestFlight and Google Play.
- **[Automations](https://capawesome.io/docs/cloud/automations/index.md)** — trigger builds, submissions, and Live Updates from Git events.
- **[Assist](https://capawesome.io/docs/cloud/assist/index.md)** — AI features in the Console, like one-click diagnoses of failed builds.

## Ways to use it

- **[Console](https://console.cloud.capawesome.io)** — manage everything from the web dashboard.
- **[CLI](https://capawesome.io/docs/cloud/cli/index.md)** — drive Capawesome Cloud from your terminal and CI/CD.
- **[API & SDKs](https://capawesome.io/docs/cloud/api/index.md)** — integrate programmatically from your own backend.
- **[MCP Server](https://capawesome.io/docs/ai/mcp/capawesome/index.md)** — manage your apps from Claude, Cursor, or any other AI assistant.

## Security

See [Security](https://capawesome.io/docs/cloud/security/index.md) for the settings and practices that protect your account, your tokens, and your signing keys. Capawesome's own certifications and infrastructure controls are documented on our [security page](https://capawesome.io/security/).

## Status & SLA

Current availability and uptime history are published on the [Capawesome Cloud status page](https://status.capawesome.io). Uptime is backed by a [Service Level Agreement](https://capawesome.io/legal/service-level-agreement/).

## Bonus: Video Walkthrough

# API

The Capawesome Cloud API lets you manage your apps and resources programmatically — apps, builds, bundles, channels, devices, deployments, and more. It's a REST API that speaks JSON, and it's the same API the [CLI](https://capawesome.io/docs/cloud/cli/index.md) and [SDKs](https://capawesome.io/docs/cloud/sdks/node/index.md) are built on. Reach for it directly when you need something those tools don't cover, or when you're integrating Capawesome Cloud into your own backend.

## Base URL

```
https://api.cloud.capawesome.io
```

The API is versioned through the URL path. All endpoints below the base URL live under a version segment such as `/v1`, so an existing integration keeps working when a new version ships.

## Authentication

Requests are authenticated with an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md). Create a token in the Console and send it as a bearer token in the `Authorization` header:

```
curl https://api.cloud.capawesome.io/v1/apps \
  -H "Authorization: Bearer $CAPAWESOME_TOKEN"
```

Keep tokens secret

Never commit a token or expose it in client-side code. Store it as a secret or environment variable, and rotate it if it might have leaked.

## Requests and responses

The API accepts and returns JSON. For requests with a body, send `Content-Type: application/json`:

```
curl -X POST https://api.cloud.capawesome.io/v1/apps \
  -H "Authorization: Bearer $CAPAWESOME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My App" }'
```

## Pagination

Endpoints that return a list of resources are paginated. Use the `limit` and `offset` query parameters to control how many items you get back and where the page starts:

```
curl "https://api.cloud.capawesome.io/v1/apps?limit=20&offset=40" \
  -H "Authorization: Bearer $CAPAWESOME_TOKEN"
```

## Errors

The API uses standard HTTP status codes: `2xx` for success, `4xx` for client errors — such as `401` for a missing or invalid token and `404` for a resource that doesn't exist — and `5xx` for server-side problems. Error responses include a JSON body describing what went wrong, so check both the status code and the message when a request fails.

## Reference

The full, interactive endpoint reference is published as an OpenAPI/Swagger specification. You can browse every endpoint, see the exact request and response shapes, and try calls directly in the browser:

[API Reference](https://api.cloud.capawesome.io/docs)

Because it's an OpenAPI spec, you can also import it into tools like Postman or feed it to a client generator to scaffold a typed SDK in your language of choice.

## Next steps

- [CLI](https://capawesome.io/docs/cloud/cli/index.md) — manage your apps from the command line.
- [Node.js SDK](https://capawesome.io/docs/cloud/sdks/node/index.md) and [Python SDK](https://capawesome.io/docs/cloud/sdks/python/index.md) — call the API from your own code.
- [API tokens](https://capawesome.io/docs/cloud/accounts/tokens/index.md) — create and manage the tokens that authenticate your requests.

# Getting Started

This is the shared first-run setup for Capawesome Cloud. Once it's done, continue with the product you want to use.

## 1. Create an account and organization

Sign up at the [Capawesome Cloud Console](https://console.cloud.capawesome.io). Your apps live inside an **organization** — one is created for you, and you can invite teammates later (see [Members](https://capawesome.io/docs/cloud/organizations/memberships/index.md)).

## 2. Install and authenticate the CLI

Install the [CLI](https://capawesome.io/docs/cloud/cli/index.md) and log in:

```
npx @capawesome/cli login
```

For CI/CD, use an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) instead. See [CLI Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md).

## 3. Create an app

Create an app to identify your project to Capawesome Cloud:

```
npx @capawesome/cli apps:create
```

On the [Apps](https://console.cloud.capawesome.io/organizations/_/apps) page, click **Create app**, provide a name, and copy the app ID.

## Next: pick a product

- [Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/index.md) — over-the-air updates.
- [Native Builds](https://capawesome.io/docs/cloud/native-builds/setup/index.md) — build native apps in the cloud.
- [App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/setup/index.md) — submit to the stores.
- [Automations](https://capawesome.io/docs/cloud/automations/setup/index.md) — trigger builds and deploys from Git.

# License Keys

License keys grant your organization access to Capawesome [Insiders SDKs](https://capawesome.io/docs/insiders/index.md). Each key is bound to one or more SDK packages and authenticates your installs against our private npm registry.

## How License Keys Work

A license key is scoped to an organization and references one or more Insiders SDK packages. When your developers or CI pipelines install one of those packages, the key authenticates the request against our private npm registry and the install is granted.

Only Owners and Admins can create, edit, rotate or delete license keys. See [Roles and Permissions](https://capawesome.io/docs/cloud/organizations/memberships/#roles-and-permissions) for details.

Adding a new SDK to a license key (whether on creation or by editing an existing key) **locks the key for 28 days**. While locked, the SDKs attached to the key cannot be changed and the key cannot be deleted. The name can still be edited, and the key can still be rotated, copied, and used to install packages. The lock prevents adding SDKs only to swap them out shortly after to gain access to more packages than your plan includes.

## Creating License Keys

To create a license key in your organization:

1. Go to the **License keys** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys).
1. Click on the **Create license key** button.
1. Enter a name for the license key.
1. Select the Insiders SDKs the license key should grant access to.
1. Read and accept the End User License Agreement (EULA).
1. Click **Create**. The new key is automatically copied to your clipboard.

Lock Period

Creating a license key with one or more SDKs locks it for 28 days. While locked, the attached SDKs cannot be changed and the key cannot be deleted. The name can still be edited, and the key can still be rotated and copied.

## Editing License Keys

To change the name or selected Insiders SDKs of a license key:

1. Go to the **License keys** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys).
1. Click on **Edit** in the "Actions" menu of the desired license key.
1. Update the name or the selected Insiders SDKs.
1. Click **Save**. Adding a new SDK starts a 28-day lock period; renaming alone does not.

## Rotating License Keys

Rotating a license key generates a new key value and immediately revokes the previous one. The lock period is **not** reset by a rotation.

1. Go to the **License keys** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys).
1. Click on **Rotate** in the "Actions" menu of the desired license key.
1. Confirm. The new key is automatically copied to your clipboard.

Rotation is Irreversible

The previous key value is revoked immediately and cannot be recovered. Update any installs and CI pipelines that depend on the key.

## Deleting License Keys

To delete a license key:

1. Go to the **License keys** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys).
1. Click on **Delete** in the "Actions" menu of the desired license key.
1. Confirm.

Applications using the deleted key will lose access to the Insiders SDKs immediately. License keys cannot be deleted while they are locked.

# Security

Security in Capawesome Cloud is shared. We secure the platform — certifications, encryption, infrastructure, vulnerability management, and incident response are documented on our [security page](https://capawesome.io/security/). You secure your account, your organization, and the pipelines that reach them. This page covers your side.

For the update path — signing bundles, protected channels, and rollbacks — see [Live Update security](https://capawesome.io/docs/cloud/live-updates/security/index.md).

## Protect your API tokens

An [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) acts on behalf of the account that created it, so it can build, publish, and deploy across every organization and app that account can reach. Read it from your CI provider's secret store or a secrets manager, never from a committed file or a hard-coded string.

Create a separate token per pipeline or integration so revoking one doesn't break the rest, rotate tokens on a schedule, and revoke a token the moment it may have been exposed — including the tokens of people who leave your team.

## Give the least privilege needed

Assign the smallest [role](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) that fits the job. A **Viewer** sees apps and their resources without being able to create a build or a deployment, which fits people who only need visibility. A **Member** can create and manage app resources but can't change organization settings or membership. Reserve **Admin** and **Owner** for the few people who manage the organization itself.

Use [teams](https://capawesome.io/docs/cloud/organizations/teams/index.md) to control which apps a member can reach, so a contractor working on one app never sees the others.

## Enforce two-factor authentication or SSO

[Enforce two-factor authentication](https://capawesome.io/docs/cloud/organizations/two-factor-authentication/index.md) for your organization. New members then need 2FA enabled before they can join, and members can't switch it off while they belong to the organization. Enforcement doesn't retroactively remove existing members without 2FA, so after enabling it, check your member list and re-invite anyone who hasn't set it up.

Alternatively, connect [single sign-on](https://capawesome.io/docs/cloud/organizations/sso/index.md) so account access follows your identity provider and offboarding happens in one place.

## Restrict network access

[Network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md) limit which networks may reach your organization, by IP allowlist, country allowlist, or both. Both fail closed: if a restriction is enabled and the address or country of a request can't be determined, the request is denied.

Restrictions apply to API tokens too, so allowlist the egress ranges of your CI runners before you switch them on — otherwise your pipelines start failing.

## Store sensitive build values as secrets

Native builds read configuration from [environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md), which hold both variables and secrets. Secrets are encrypted at rest and in transit, and their values never appear in build logs. Ad-hoc variables passed when triggering a build are not encrypted and can show up in logs, so keep them for values you don't mind exposing.

## Guard your signing keys and certificates

To build and sign on your behalf, Capawesome Cloud stores the [signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) you upload: an Android keystore, an iOS distribution certificate and provisioning profile, and a web signing key if Capawesome Cloud signs your Live Update bundles.

Keep your own backup of every key outside Capawesome Cloud, never commit one to version control, and replace it if you suspect exposure. Losing an Android keystore means you can no longer update that app in the Play Store. If you'd rather Capawesome Cloud never held your Live Update signing key, [sign bundles in your own pipeline](https://capawesome.io/docs/cloud/live-updates/security/#sign-your-bundles) instead.

## Review audit logs

[Audit logs](https://capawesome.io/docs/cloud/organizations/audit-logs/index.md) record who created, changed, or deleted apps, bundles, channels, invitations, members, organizations, and subscriptions, and you can filter them by entity, action, and user. Only owners and admins can read them. Check them after offboarding someone, and whenever you find a deployment nobody on the team remembers making.

## Next steps

- [Live Update security](https://capawesome.io/docs/cloud/live-updates/security/index.md) — sign your bundles, protect channels, and enable automatic rollbacks.
- [API tokens](https://capawesome.io/docs/cloud/accounts/tokens/index.md) — create, use, rotate, and revoke tokens.
- [Roles and permissions](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) — what each role can do.

# Authentication

Capawesome Cloud provides multiple authentication methods to securely access your account. You can choose between email/password authentication and OAuth providers, or use both methods simultaneously.

## Authentication Methods

Capawesome Cloud supports the following authentication methods:

- **Email/Password**: Traditional authentication using your email address and a password.
- **OAuth**: Single sign-on using your GitHub, GitLab, or Bitbucket account.

Both authentication methods can be configured and managed through the [account settings](https://console.cloud.capawesome.io/settings/account).

## Setting Up Email/Password Authentication

To enable email/password authentication:

1. Go to the [account settings](https://console.cloud.capawesome.io/settings/account) in the Capawesome Cloud Console.
1. Scroll to the **Password** section.
1. Set a password for your account by entering your desired password and confirming it.
1. Click **Save** to enable email/password authentication.

Once configured, you can use your email address and password to sign in to Capawesome Cloud.

## Setting Up OAuth Authentication

To set up OAuth authentication:

1. Go to the [account settings](https://console.cloud.capawesome.io/settings/account) in the Capawesome Cloud Console.
1. Scroll to the **Identities** section.
1. Click on the **Connect** button next to your preferred provider (GitHub, GitLab, Bitbucket, or Microsoft).
1. Follow the authorization flow to connect your account.

Once linked, you can use the OAuth provider to sign in to Capawesome Cloud. You can add or remove OAuth providers at any time by visiting the account settings and clicking the **Disconnect** button next to the provider you want to remove.

## Two-Factor Authentication (MFA)

Two-factor authentication adds an extra layer of security to your account by requiring a second form of verification in addition to your password. Capawesome Cloud supports time-based one-time passwords (TOTP) using authenticator apps.

### Enabling MFA

To enable two-factor authentication:

1. Go to the [account settings](https://console.cloud.capawesome.io/settings/account) in the Capawesome Cloud Console.
1. Scroll to the **Two-factor authentication** section.
1. Follow the on-screen instructions to set up MFA:
1. Scan the QR code with your authenticator app (such as Google Authenticator or Authy).
1. Enter the verification code generated by your authenticator app.
1. Click **Enable** to activate MFA for your account.

Once enabled, you will be prompted to enter a verification code from your authenticator app each time you sign in.

## Recovery Codes

Recovery codes are backup codes that can be used to regain access to your account if you lose access to your authenticator device. It is highly recommended to generate and store these codes in a safe place when enabling MFA.

### Generating Recovery Codes

To generate recovery codes:

1. Go to the [account settings](https://console.cloud.capawesome.io/settings/account) in the Capawesome Cloud Console.
1. Scroll to the **Recovery codes** section.
1. Click on the **Generate** button.
1. Download or copy the generated recovery codes and store them securely.

Each recovery code can only be used once. If you run out of recovery codes or lose them, you can regenerate new codes at any time by following the same steps above.

# API Tokens

API tokens authenticate the [CLI](https://capawesome.io/docs/cloud/cli/index.md) and the [Cloud API](https://capawesome.io/docs/cloud/api/index.md) without an interactive login — they're how you run Capawesome Cloud commands in CI/CD pipelines and scripts, where there's nobody to log in by hand.

A token acts on behalf of the account that created it, so it can do whatever you can do across the organizations and apps you have access to. Treat it like a password: anyone holding the token can act as you.

## Create a token

Create a token in the [Capawesome Cloud Console](https://console.cloud.capawesome.io) from your account settings. The token is shown **only once**, so copy it immediately and store it somewhere safe — if you lose it, you'll need to create a new one rather than retrieve the old.

## Use a token

You can use a token two ways.

With the **CLI**, store the token as a secret in your CI provider and pass it with `--token`:

```
npx @capawesome/cli login --token "$CAPAWESOME_TOKEN"
```

With the **Cloud API**, send it as a bearer token in the `Authorization` header:

```
curl https://api.cloud.capawesome.io/v1/apps \
  -H "Authorization: Bearer $CAPAWESOME_TOKEN"
```

See [CLI Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md) and the [Cloud API](https://capawesome.io/docs/cloud/api/index.md) for more.

Info

If an organization uses [network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md), tokens are subject to them too. A pipeline running on a hosted CI runner will be blocked unless the runner's egress ranges are allowlisted.

Keep tokens secret

Never commit a token to version control or hard-code it. Always read it from a secret or environment variable, and revoke any token that may have been exposed.

## Revoke a token

Revoke a token at any time from the Console. Once revoked, it can no longer authenticate, and any pipeline still using it will start failing — so update your secrets when you rotate.

## Best practices

- **Use a separate token per pipeline or integration.** If one leaks or needs revoking, you only break that one place instead of everything at once.
- **Rotate periodically.** Replace long-lived tokens on a schedule, and immediately if you suspect one was exposed.
- **Store it as a secret, never in plain text.** Use your CI provider's secret store or a secrets manager, not a committed file or environment dump.

# App Store Publishing

Use [Capawesome Cloud](/) to automate your app store submissions. Submit builds directly to TestFlight, the App Store, Google Play tracks, and Huawei AppGallery without manual uploads, or distribute them to testers via Firebase App Distribution.

## Features

- 🚀 **Automatic Submissions**: Submit builds directly to TestFlight, App Store, Google Play tracks, and Huawei AppGallery, or distribute them via Firebase App Distribution.
- ⚙️ **One-Time Setup**: Configure your store destinations once, then deploy automatically with every build.
- 🔗 **Seamless Integration**: Works perfectly with Native Builds to create a complete CI/CD pipeline.
- 🎯 **Multiple Tracks**: Support for Internal, Alpha, Beta, and Production tracks on Google Play.
- 🍎 **TestFlight and App Review**: Upload iOS builds to TestFlight, distribute them to external beta groups, and submit them for App Review.
- 📝 **Release Notes**: Publish release notes with each submission, translated into multiple languages.
- 📦 **Flexible Formats**: Submit Android apps as AAB or APK formats.
- 🔐 **Secure Credentials**: Store App Store Connect, Google Play, Huawei AppGallery, and Firebase credentials securely.
- 📱 **Multi-Platform**: Submit both iOS and Android apps from the same platform.
- 📚 **Documentation**: Comprehensive documentation to help you get started.

## Getting Started

- **Setup App Store Publishing**

  ______________________________________________________________________

  Configure a store destination and submit your first build.

  ______________________________________________________________________

  [Getting Started](https://capawesome.io/docs/cloud/app-store-publishing/setup/index.md)

## Documentation

- **Destinations**

  ______________________________________________________________________

  Learn how to create and manage store destinations for your apps.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md)

- **Submit a Build**

  ______________________________________________________________________

  Submit a build to TestFlight, Google Play, Huawei AppGallery, or Firebase App Distribution.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md)

- **Release Notes**

  ______________________________________________________________________

  Publish release notes with each submission, translated into multiple languages.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md)

- **App Review**

  ______________________________________________________________________

  Distribute iOS builds to TestFlight beta groups and submit them for App Review.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md)

- **Submit Automatically**

  ______________________________________________________________________

  Submit every successful build to a store automatically.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md)

- **Troubleshooting**

  ______________________________________________________________________

  Find solutions to common app store submission issues.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/troubleshooting/index.md)

- **FAQ**

  ______________________________________________________________________

  Find answers to frequently asked questions about App Store Publishing.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/faq/index.md)

# FAQ

### Which stores are supported?

App Store Connect (TestFlight and the App Store), Google Play, and Huawei AppGallery. Test builds can also be distributed via Firebase App Distribution. See [Destinations](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md).

### Do I need to upload the first version manually?

For **Google Play**, yes — Google requires the very first version of an app to be uploaded manually to the Play Console. Subsequent builds can be submitted automatically. For **Apple**, no manual first upload is required, but the first App Store version can't carry release notes when the destination submits it for review, while TestFlight's What to Test is unaffected — see [below](#why-cant-the-first-app-store-version-have-release-notes).

### How do I authenticate with App Store Connect?

With an App Store Connect **API key** (recommended) or your **Apple ID** with an app-specific password. Beta groups, App Review submission, and release notes require the API key. See the [App Store Connect destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md).

### Can I submit iOS builds for App Review?

Yes — enable **Submit for App Review** on the App Store Connect destination. Every build still goes to TestFlight first; the destination can additionally distribute it to external beta groups. See [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md).

### Can I add release notes to a submission?

Yes — pass a default text and optional translations with the CLI, the API, or the MCP server, or enter the default text in the Console. Google Play and Huawei AppGallery accept up to 500 characters per language, App Store Connect and Firebase App Distribution up to 4,000. See [Add release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md).

### Can automations add release notes?

No. Submissions from an [automation](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) leave the release notes unchanged, so an App Store Connect destination with [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups), which requires release notes, can't be used with an automation.

### Why can't the first App Store version have release notes?

Apple rejects **What's New** on the very first App Store version of an app. Release notes only fail when the destination submits for review; TestFlight's What to Test is unaffected. Deploy the first version without release notes, and Capawesome Cloud submits it without **What's New**. Or use a destination with **Submit for App Review** turned off and submit the version in App Store Connect yourself. Later versions can carry release notes. See [First App Store version](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#first-app-store-version).

### Which Google Play tracks are supported?

Internal, Alpha, Beta, and Production. Set the track on the [Google Play destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md). Builds with a Wear OS, Android TV, or Automotive module also use the prefixed tracks `wear:<track>`, `tv:<track>`, and `automotive:<track>` — see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

### Can I submit automatically on every release?

Yes — attach a destination to an [automation](https://capawesome.io/docs/cloud/automations/index.md). See [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md).

### Why did my submission fail?

The fastest way to find out is [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md) on the failed deployment. See also [Troubleshooting](https://capawesome.io/docs/cloud/app-store-publishing/troubleshooting/index.md).

# Add Release Notes

Release notes tell your testers and users what changed in a build. When you [submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) to a [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md), you can attach release notes to the submission, and Capawesome Cloud publishes them where the store shows them: **What to Test** in TestFlight, **What's New** on the App Store and Google Play, **New features** on Huawei AppGallery, and the release notes of a Firebase App Distribution release.

Release notes consist of a **default text** and optional **translations** keyed by locale, such as `de-DE`, `pt-BR`, `zh-Hans`, or `es-419`. They are optional: without them, Capawesome Cloud leaves the release notes in the store unchanged.

## Add release notes to a submission

Pass the default text with `--release-notes` and a translation with `--release-notes-locale`, which you can repeat, to [`apps:deployments:create`](https://capawesome.io/docs/cloud/cli/commands/#appsdeploymentscreate):

```
npx @capawesome/cli apps:deployments:create --build-number 42 --destination my-destination \
  --release-notes "Bug fixes and performance improvements." \
  --release-notes-locale de-DE="Fehlerbehebungen und Leistungsverbesserungen."
```

Alternatively, keep all texts in a JSON file with a `default` key and one key per locale:

```
{
  "default": "Bug fixes and performance improvements.",
  "de-DE": "Fehlerbehebungen und Leistungsverbesserungen."
}
```

Then pass the file with `--release-notes-file`, which can't be combined with the other two flags:

```
npx @capawesome/cli apps:deployments:create --build-number 42 --destination my-destination --release-notes-file release-notes.json
```

To use a plain text file as the default text, pass its content with `--release-notes="$(cat release-notes.txt)"`. The `=` keeps a text that starts with a hyphen, such as a bulleted list, from being read as a flag.

To build and submit in one go, pass the same three flags to [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) together with `--destination`. The build is submitted with its release notes once it finishes:

```
npx @capawesome/cli apps:builds:create --platform ios --type app-store --git-ref v1.2.0 \
  --destination my-destination --release-notes-file release-notes.json
```

Enter the text in the **Release notes** field of the **Create deployment** dialog on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page. When you create a build with **Deploy build after completion** checked, the build dialog offers the same field. The Console only sets the default text.

The official [`cloud-build-action`](https://github.com/capawesome-team/cloud-build-action) takes the default text with the `releaseNotes` input, or a JSON file with translations with `releaseNotesFile`. Both require the `destination` input and can't be combined:

```
- uses: capawesome-team/cloud-build-action@v0.1.4
  with:
    appId: "00000000-0000-0000-0000-000000000000"
    platform: ios
    type: app-store
    gitRef: ${{ github.ref_name }}
    certificate: "Production"
    destination: "TestFlight"
    releaseNotesFile: release-notes.json
    token: ${{ secrets.CAPAWESOME_TOKEN }}
```

See [Native Builds with GitHub Actions](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md) for the workflow basics.

To add release notes from your own code, pass the `releaseNotes` object to the [API](https://capawesome.io/docs/cloud/api/index.md) when you create a deployment at `/v1/apps/{appId}/deployments`, or a build with a destination at `/v1/apps/{appId}/builds`. The [Capawesome MCP server](https://capawesome.io/docs/ai/mcp/capawesome/index.md) accepts the same object.

## Where release notes appear

Each store shows release notes in a different place and limits their length:

| Destination                                                                                                                              | Where the release notes appear                                                                                                                                                                                                                                    | Limit per language |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| [App Store Connect](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/#release-notes)                   | **What to Test** in TestFlight, default text only. With [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md), also **What's New** of the App Store version, including translations. Requires an API key. | 4,000 characters   |
| [Google Play](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/#release-notes)                       | **What's new** of the track release. The default text goes to the destination's default language, `en-US` if none is set.                                                                                                                                         | 500 characters     |
| [Huawei AppGallery](https://capawesome.io/docs/cloud/app-store-publishing/destinations/huawei-appgallery/#release-notes)                 | **New features** of the app version. The default text goes to the destination's default language, `en-US` if none is set.                                                                                                                                         | 500 characters     |
| [Firebase App Distribution](https://capawesome.io/docs/cloud/app-store-publishing/destinations/firebase-app-distribution/#release-notes) | Release notes of the release, default text only.                                                                                                                                                                                                                  | 4,000 characters   |

Google Play and Huawei AppGallery publish the default text in the destination's **Default language**. Set it on the destination if the default language of your store listing isn't `en-US`.

## Limitations

- **Destinations only**: Release notes are supported for submissions to destinations, not for Live Update channels.
- **No automations**: [Automations](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) can't provide release notes, so their submissions leave the release notes in the store unchanged. An App Store Connect destination with [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups) requires release notes, so submit to such a destination with the CLI instead.
- **Fixed once submitted**: Release notes can't be changed after the deployment is created. To change them, edit them in the store.
- **First App Store version**: Apple rejects **What's New** on the very first App Store version of an app. See [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#first-app-store-version).

## Next steps

- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — the full submission workflow.
- [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md) — distribute to TestFlight beta groups and submit to the App Store, with release notes as What to Test and What's New.
- [`apps:deployments:create` reference](https://capawesome.io/docs/cloud/cli/commands/#appsdeploymentscreate) — every release notes flag.

# Getting Started

App Store Publishing submits your [native builds](https://capawesome.io/docs/cloud/native-builds/index.md) straight to TestFlight and the App Store, Google Play, Huawei AppGallery, and Firebase App Distribution — no manual uploads. Set up a destination once, then submit any build to it.

## Step 1: Create a Destination

A **destination** holds the store credentials and configuration to submit to. Create one for the store you're targeting:

- [App Store Connect](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md) — authenticate with an Apple ID or App Store Connect API key, and optionally submit for App Review.
- [Google Play](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md) — authenticate with a service account and choose a release track.
- [Huawei AppGallery](https://capawesome.io/docs/cloud/app-store-publishing/destinations/huawei-appgallery/index.md) — authenticate with an AppGallery Connect API client and choose whether to submit for review.
- [Firebase App Distribution](https://capawesome.io/docs/cloud/app-store-publishing/destinations/firebase-app-distribution/index.md) — authenticate with a service account and choose the tester groups.

## Step 2: Submit Your First Build

With a destination configured, submit an existing native build to it:

```
npx @capawesome/cli apps:deployments:create
```

The CLI prompts for the build and destination.

Open the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page, click **Create deployment**, select a build and the destination, and confirm.

See [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) for details.

## Step 3: Verify

For **Apple**, the build is uploaded to TestFlight — check App Store Connect once processing completes. For **Google**, the build appears on the selected track in the Play Console. For **Huawei**, check AppGallery Connect, and for **Firebase**, the App Distribution section of the Firebase console.

## Next steps

- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — submit on every build with an automation.
- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — the full manual workflow.

# Submit a Build

Submitting a build sends a finished [native build](https://capawesome.io/docs/cloud/native-builds/index.md) straight to App Store Connect (TestFlight and the App Store), Google Play, Huawei AppGallery, or Firebase App Distribution — no manual uploads through Xcode or a web console. Under the hood, each submission creates a **deployment** to a [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md), so you can submit any build with a single command or click.

## Prerequisites

Before you can submit, you need:

- A successful [native build](https://capawesome.io/docs/cloud/native-builds/builds/index.md) for the platform you're submitting (a signed build matching the store's requirements).
- A configured [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) — the store credentials and settings the build is submitted to. See [Getting Started](https://capawesome.io/docs/cloud/app-store-publishing/setup/index.md) to set one up.

## Submit

Use the [`apps:deployments:create`](https://capawesome.io/docs/cloud/cli/commands/#appsdeploymentscreate) command, identifying the build by its number (or ID) and the destination to submit to:

```
npx @capawesome/cli apps:deployments:create --build-number 42 --destination my-destination
```

The CLI prompts for the build and destination if you don't pass them. Add `--detached` to return immediately instead of waiting for the submission to finish — useful in scripts and CI.

Open the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page, click **Create deployment**, select the build to submit and the destination, then confirm.

To tell your testers and users what changed, add [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) to the submission.

## After submitting

What happens next depends on the store:

- **App Store Connect** — the build is uploaded to TestFlight. Once App Store Connect finishes processing it (typically 10 to 30 minutes), it becomes available to internal TestFlight groups with automatic distribution enabled and is ready to promote to an App Store release; other internal groups need it assigned manually in App Store Connect. External testers only receive the build through the destination's [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups), and the destination can also [submit it for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md).
- **Google Play** — the build is published to the destination's configured track: **Internal**, **Alpha**, **Beta**, or **Production**.
- **Huawei AppGallery** — the build is uploaded to AppGallery Connect. With the release status **Completed**, the version is also submitted for review.
- **Firebase App Distribution** — the build is uploaded to Firebase and distributed to the destination's tester groups, if any.

An Android build can contain more than one artifact, for example a phone app and a Wear OS app. Google Play receives all of them, mobile first, each to the track of its form factor (`wear:<track>`, `tv:<track>`, `automotive:<track>`). Capawesome Cloud validates every artifact against Google Play before it publishes the first one, so a missing track fails the submission before the phone app is released. Huawei AppGallery and Firebase App Distribution receive only the phone app. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

Keep in mind that the stores run their own processing and review after Capawesome Cloud hands off the build, so a successful deployment means the build was *submitted* — not yet that it's live.

## Track the submission

Follow a deployment's status or stream its logs:

```
npx @capawesome/cli apps:deployments:list
npx @capawesome/cli apps:deployments:logs
```

Add `--json` to `apps:deployments:get` or `apps:deployments:list` for machine-readable output, including timing and the related job — handy for debugging a failed submission in CI.

Watch the deployment's status update live on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page, and open it to read the logs.

If a submission is still running and you need to stop it, cancel it with `apps:deployments:cancel` or from its detail page in the Console.

## Next steps

- [Add release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) — tell testers and users what changed.
- [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md) — distribute iOS builds to beta groups and submit them to the App Store.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — skip this step on every release.
- [Destinations](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) — configure the credentials and settings for each store.
- [Troubleshooting](https://capawesome.io/docs/cloud/app-store-publishing/troubleshooting/index.md) — fix a failed submission.

# Submit Automatically After a Build

You can submit to a store automatically on every build by attaching a [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) to an [automation](https://capawesome.io/docs/cloud/automations/index.md). When a Git event triggers a build, Capawesome Cloud builds the app and submits the resulting artifact to the destination — a complete Git → build → store pipeline.

## Set it up

1. Create a [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) for the store you're targeting.
1. Create an [automation](https://capawesome.io/docs/cloud/automations/index.md) with the trigger you want (for example, a `v*` tag for releases).
1. In the automation's build settings, select the **destination** to submit to.

Now every matching push or tag builds your app and submits it automatically. See [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) for the full walkthrough.

Automations can't provide [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md), and an App Store Connect destination with [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups) requires them, so submit to such a destination with the CLI instead.

## Recommended pattern

A common setup is to submit release tags to TestFlight or an internal track:

- Trigger on tags matching `v*`.
- Attach the signing certificate and the store destination.

This keeps releases deliberate (they ship when you create a tag) while removing all the manual upload steps.

## Next steps

- [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) — the full walkthrough.
- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — submit a build manually.
- [Add release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) — not available for automations.

# Submit for App Review

Every submission to an [App Store Connect destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md) uploads the build to TestFlight. With an App Store Connect API key, the destination can go further: distribute the build to external TestFlight **beta groups** and submit it for **App Review**, so a single deployment takes a build from Capawesome Cloud to the App Store.

## Prerequisites

- **API key**: The destination must use the `API Key` authentication method. Destinations with an Apple ID and app-specific password can only upload to TestFlight. See [API Key Credentials](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/#api-key-credentials).

- **Export compliance**: Your app's `Info.plist` must declare `ITSAppUsesNonExemptEncryption`. Otherwise, the deployment fails before the upload with the message "Info.plist must declare ITSAppUsesNonExemptEncryption for TestFlight external distribution and App Store submission". Capawesome Cloud never answers Apple's export compliance question on your behalf. See Apple's guide on [complying with encryption export regulations](https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations) to pick the right value. For example, an app that uses no non-exempt encryption declares:

  ```
  <key>ITSAppUsesNonExemptEncryption</key>
  <false/>
  ```

- **Test Information**: Beta App Review needs the **Test Information** of your app in App Store Connect under **TestFlight**, such as the contact details and a demo account if your app requires a sign-in. Fill it in once per app before the first distribution to a beta group.

- **App Store listing**: A submission only sets **What's New**. Screenshots, description, and all other metadata stay as they are in App Store Connect, so complete them there before your first submission.

## Configure the destination

The destination decides what happens after the upload:

- **Beta groups**: The external TestFlight beta groups to distribute the build to, up to 20. Enter the group names exactly as they appear in App Store Connect. See [Distribute to beta groups](#distribute-to-beta-groups).
- **Submit for App Review**: Submit the build for App Review after the upload. The build still goes to TestFlight first, so this option means TestFlight **and** the App Store, never the App Store only.
- **Release type**: Apple's version release setting for the submitted version. With `Manual` (default), you release the approved version yourself. With `After approval`, Apple releases it automatically once App Review approves it.
- **Cancel pending submission**: Cancel a submission that is waiting for review before submitting the new build.

Set the options with [`apps:destinations:create`](https://capawesome.io/docs/cloud/cli/commands/#appsdestinationscreate) or [`apps:destinations:update`](https://capawesome.io/docs/cloud/cli/commands/#appsdestinationsupdate):

```
npx @capawesome/cli apps:destinations:update --app-id <app-id> --destination-id <destination-id> \
  --apple-beta-group "External Testers" \
  --apple-submit-for-review \
  --apple-release-type after-approval \
  --apple-reject-if-possible
```

`--apple-beta-group` can be repeated or take a comma-separated list. Pass `--apple-beta-group=` to remove all groups, and `--apple-submit-for-review false` or `--apple-reject-if-possible false` to turn the options off again. `--apple-release-type` accepts `manual` or `after-approval`.

Open the destination on the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page. With the authentication method `API Key`, the dialog shows the **Beta groups** field and the **Submit for App Review** checkbox. **Release type** and **Cancel pending submission** appear once **Submit for App Review** is checked.

## Distribute to beta groups

Once Apple has processed an uploaded build, it is available in TestFlight to your internal groups with automatic distribution enabled, whatever the destination's settings. Other internal groups need the build assigned manually in App Store Connect, and external testers only receive it through the destination's beta groups.

With beta groups set, the deployment waits until Apple has processed the build, distributes it to the groups, and submits it for Beta App Review. Apple reviews the build asynchronously, so the deployment finishes before the review does, and your testers are notified once Apple has approved the build.

Deployments to a destination with beta groups require [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md), which become **What to Test** in TestFlight. Since [automations](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) can't provide release notes, submit such builds with the CLI instead.

## How the submission works

With **Submit for App Review**, a deployment runs these steps:

1. Upload the build to TestFlight, with the default [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) as **What to Test** when release notes are given.
1. If the destination has beta groups, wait until Apple has processed the build, distribute it to the groups, and submit it for Beta App Review.
1. Create the App Store version matching the build's version. If a version with a different number is currently editable in App Store Connect, for example one you prepared by hand, it is renamed to the build's version instead of creating a second one, since Apple allows only one editable version.
1. When release notes are given, write them to **What's New**: the default text for every language of the version, then each translation for its language. Provide translations only for the languages of your App Store listing, since a translation for another language creates a new localization of the version.
1. Wait until Apple has processed the build and attach it to the version.
1. Cancel a pending submission if **Cancel pending submission** is checked, then submit the version for App Review with the configured release type.

Apple typically needs 10 to 30 minutes to process a build. With beta groups or App Review submission, the deployment waits for this processing, and the waiting time counts toward your [build minutes](https://capawesome.io/docs/cloud/native-builds/limits/#build-minutes). Without them, the deployment finishes right after the upload.

Automations can submit for App Review too: attach the destination to an [automation](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md), and every matching tag is built, uploaded, and submitted. Their submissions carry no release notes, so **What's New** stays as it is in App Store Connect.

### First App Store version

Apple rejects **What's New** on the very first App Store version of an app. Release notes only fail when the destination submits for review, since TestFlight's What to Test is unaffected. Deploy the first version without release notes, and Capawesome Cloud submits it without **What's New**. Or use a destination with **Submit for App Review** turned off and submit the version in App Store Connect yourself. Later versions can carry release notes.

## After a failed submission

If the submission fails after the build was attached, the prepared version stays in App Store Connect. Fix the cause shown in the deployment logs, then submit the version in App Store Connect or deploy a new build, which reuses the editable version. See [Troubleshooting](https://capawesome.io/docs/cloud/app-store-publishing/troubleshooting/index.md) for the common errors.

## Next steps

- [Add release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) — What to Test for testers and What's New for the App Store.
- [App Store Connect destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md) — credentials and the destination's other settings.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — submit every release tag for App Review with an automation.

# Troubleshooting

## First, try Ask AI

On any failed deployment, click **Ask AI** in the Console for a one-click diagnosis with the likely cause and a suggested fix. See [Cloud Assist → Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md).

## Submission not appearing in TestFlight

After a successful submission, Apple needs time to process the build before it shows up in TestFlight — this can take several minutes. If it still doesn't appear:

- Confirm the destination's **Team ID** and credentials are correct.
- Check that the build's version and build number are higher than any existing build.
- Review the deployment logs for an App Store Connect error.

## Deployment fails with "Info.plist must declare ITSAppUsesNonExemptEncryption"

Distributing to beta groups and submitting for App Review require your app's `Info.plist` to declare `ITSAppUsesNonExemptEncryption`. Capawesome Cloud doesn't answer Apple's export compliance question on your behalf, so the deployment fails before the upload. Add the key to your app's `Info.plist` (`ios/App/App/Info.plist` in a Capacitor project), commit the change, and rebuild before deploying again. Use `false` if your app only uses exempt encryption such as HTTPS; see Apple's guide on [complying with encryption export regulations](https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations) if you are unsure, and the [prerequisites](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#prerequisites) for App Review submission.

```
<key>ITSAppUsesNonExemptEncryption</key>
<false/>
```

## TestFlight deployment fails with "No changelog provided"

The App Store Connect destination has beta groups, which require release notes for **What to Test**, but the deployment has none. This happens when an [automation](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) submits to such a destination, since automations can't provide release notes. Submit the build with [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) instead, or remove the [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups) from the destination.

## Release notes or App Review settings require an API key

Beta groups, **Submit for App Review**, and release notes only work with App Store Connect **API key** authentication. With an Apple ID and app-specific password, the Console doesn't offer these settings and the CLI and API reject them. Switch the destination's authentication method to `API Key` — see the [App Store Connect destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/#api-key-credentials).

## First App Store version fails with release notes

Apple rejects **What's New** on the very first App Store version of an app. Release notes only fail when the destination submits for review, since TestFlight's What to Test is unaffected. Deploy the first version without release notes, and Capawesome Cloud submits it without **What's New**. Or use a destination with **Submit for App Review** turned off and submit the version in App Store Connect yourself. See [First App Store version](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#first-app-store-version).

## App Review submission failed

If the submission fails after the build was attached, the prepared App Store version stays in App Store Connect. Check the deployment logs for Apple's error, fix the cause, then submit the version in App Store Connect or deploy a new build. Capawesome Cloud only sets **What's New**, so make sure the rest of the App Store listing, such as the screenshots, is complete in App Store Connect. See [After a failed submission](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#after-a-failed-submission).

## Google Play submission rejected

- For a brand-new app, the **first version must be uploaded manually** to the Play Console before automated submissions work.
- Confirm the service account has the required permissions in the Play Console.
- Check that the **package name**, **track**, and **release status** on the destination match your app.

## Still stuck?

Reach out via [Support](https://capawesome.io/docs/support/index.md) with a link to the failed deployment and its logs.

# Set Up a Store Destination

Configure destinations to automatically submit your native builds to app stores and testers. Capawesome Cloud supports direct submissions to App Store Connect (TestFlight and the App Store), Google Play, and Huawei AppGallery, and distributes test builds via Firebase App Distribution, streamlining your release process. Each submission can carry release notes in multiple languages.

- **App Store Connect**

  ______________________________________________________________________

  Configure automatic submissions to TestFlight, external beta groups, and App Review.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md)

- **Firebase App Distribution**

  ______________________________________________________________________

  Configure automatic distribution of Android and iOS builds to your testers.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/destinations/firebase-app-distribution/index.md)

- **Google Play**

  ______________________________________________________________________

  Configure automatic submissions to Google Play tracks.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md)

- **Huawei AppGallery**

  ______________________________________________________________________

  Configure automatic submissions to Huawei AppGallery.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/app-store-publishing/destinations/huawei-appgallery/index.md)

# App Store Connect

To submit your iOS app builds to TestFlight and the App Store, you need to configure an App Store Connect destination in the Capawesome Cloud Console. Every submission is uploaded to TestFlight. Depending on the destination's settings, the build is also distributed to external beta groups and submitted for App Review.

AI-Assisted Setup

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill capawesome-cloud` and use the following prompt with your preferred AI coding assistant:

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up an App Store Connect destination in Capawesome Cloud.
```

## Configuration

To create an App Store Connect destination, navigate to the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for this destination (e.g., "Production iOS", "TestFlight Beta").
- **Platform**: Must be set to `iOS`.
- **Type**: Must be set to `App Store Connect`.
- **Authentication method**: Choose how to authenticate with App Store Connect. You can use either `Apple ID + Password` or `API Key`. [Beta groups, App Review submission](#testflight-and-app-review), and [release notes](#release-notes) require `API Key`.
- **Team ID**: Your Apple Developer Team ID from the Membership Details section.

Depending on the authentication method you choose, you will need to provide additional credentials:

### Apple ID + Password

- **Apple ID**: Your Apple ID email address.
- **Apple App ID**: The Apple ID property from the App Information section in App Store Connect.
- **App-specific password**: An app-specific password generated on your Apple ID account page.

### API Key

- **API Key File**: The `.p8` private key file downloaded from App Store Connect.
- **Key ID**: The Key ID associated with your API key.
- **Issuer ID**: The Issuer ID from App Store Connect.

Read on for instructions on obtaining these credentials.

## Obtaining Credentials

### Team ID

1. Sign in to your [Apple Developer account](https://developer.apple.com/account).
1. Scroll down to **Membership Details**.
1. Copy your **Team ID**.

### Apple ID + Password Credentials

#### Apple ID

This is the email address associated with your Apple Developer account.

#### Apple App ID

1. Sign in to [App Store Connect](https://appstoreconnect.apple.com).
1. Navigate to **Apps** and select your app.
1. Go to **App Information**.
1. Copy the **Apple-ID** value (a numeric identifier).

#### App-specific Password

1. Sign in to your [Apple ID account page](https://appleid.apple.com).
1. Navigate to **Security** section.
1. Under **App-Specific Passwords**, click **Generate Password**.
1. Enter a descriptive label (e.g., "Capawesome Cloud").
1. Copy the generated password and save it securely.

### API Key Credentials

#### API Key File, Key ID, and Issuer ID

1. Sign in to [App Store Connect](https://appstoreconnect.apple.com).
1. Navigate to **Users and Access**.
1. Select the **Integrations** tab, then select **App Store Connect API**. **Note**: If you do not see this tab, ensure that your account has the necessary permissions (Admin or App Manager role).
1. Click the **+** button to create a new **Team Key**.
1. Enter a name for the key (e.g., "Capawesome Cloud") and select **App Manager** as the access level.
1. Click **Generate**.
1. Copy the **Issuer ID** displayed at the top of the page.
1. Copy the **Key ID** from the newly created key row.
1. Click **Download API Key** to download the `.p8` file. **Note**: You can only download this file once, so store it securely.

## TestFlight and App Review

Every submission uploads the build to TestFlight. With the `API Key` authentication method, the destination can also distribute the build to external TestFlight beta groups and submit it for App Review:

- **Beta groups**: The external TestFlight beta groups to distribute the build to, up to 20.
- **Submit for App Review**: Submit the build for App Review after the upload.
- **Release type**: Whether you release the approved version yourself (`Manual`) or Apple releases it automatically (`After approval`).
- **Cancel pending submission**: Cancel a submission that is waiting for review before submitting the new build.

See [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md) for the prerequisites, how to set these options, and what a submission does step by step.

## Release Notes

[Release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) require the `API Key` authentication method and may be up to 4,000 characters per language:

- **TestFlight**: The default text becomes **What to Test**. TestFlight doesn't support translations, and fastlane removes emoji and `<` characters from the text and truncates it at 4,000 bytes before uploading it.
- **App Store**: With **Submit for App Review**, the release notes also become **What's New** of the App Store version. Only then are translations accepted. Apple rejects **What's New** on the [very first App Store version](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#first-app-store-version) of an app.

## Common Issues

### Submission not appearing in TestFlight

It may **take some time for the build to process** in App Store Connect before it appears in TestFlight. If your build does not appear after a reasonable amount of time, make sure to check your email inbox for any processing errors or issues notified by Apple.

The most common reasons for this can be:

- Build number was not incremented
- Missing Privacy Descriptions in your app's `Info.plist`
- Incorrect build settings or configurations
- App Store Connect account permissions are insufficient (account must have at least App Manager role)

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers setting up an App Store Connect destination end to end:

## Next steps

- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — send a build to your new destination.
- [Submit for App Review](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/index.md) — distribute to beta groups and submit to the App Store.
- [Add release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) — What to Test for testers and What's New for the App Store.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — submit every release with an automation.
- [Troubleshooting](https://capawesome.io/docs/cloud/app-store-publishing/troubleshooting/index.md) — fix a failed submission.

# Firebase App Distribution

To distribute your Android and iOS app builds to testers, you need to configure a Firebase App Distribution destination in the Capawesome Cloud Console. App submissions are uploaded to Firebase App Distribution and distributed to the configured tester groups.

## Configuration

To create a Firebase App Distribution destination, navigate to the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for this destination (e.g., "QA Android", "Beta iOS").
- **Platform**: Either `Android` or `iOS`.
- **Type**: Must be set to `Firebase App Distribution`.
- **App ID**: The Firebase app ID of your app (e.g., `1:123456789012:android:0a1b2c3d4e5f67890`).
- **Tester groups**: The aliases of the tester groups to distribute the build to (optional).
- **JSON Key File**: Service account JSON key file from Google Cloud Console.
- **Publishing format**: The app bundle format (`AAB` or `APK`). Android only.

Read on for detailed instructions on obtaining the required credentials.

## Obtaining Credentials

### Firebase App ID

Each app in a Firebase project has its own app ID in the format `1:<projectNumber>:<platform>:<hash>`, where the platform is `android` or `ios`. Use the app ID that matches the platform of the destination. You can find it in the [Firebase console](https://console.firebase.google.com/) under **Project settings** > **General** in the **Your apps** section.

### Tester Groups

Tester groups are identified by their alias (e.g., `qa-team`), which you can find with each group in the App Distribution section of the Firebase console. You can add up to 20 groups. If you don't add any, the build is uploaded without being distributed to a group.

### JSON Key File

A service account JSON key file is required to authenticate with Firebase. The service account needs the **Firebase App Distribution Admin** role in the Google Cloud project of your Firebase project.

To obtain the service account JSON key file:

1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) and select the Google Cloud project of your Firebase project.
1. Navigate to **IAM & Admin** > **Service Accounts**.
1. Create a new service account by clicking **Create Service Account**.
1. In step 1, fill in the service account details and click **Create and Continue**.
1. In step 2, assign the role **Firebase App Distribution Admin** and click **Continue**.
1. In step 3, you can leave the fields empty and click **Done**.
1. In the list of service accounts, locate the newly created service account. Click on the menu in the Actions column and select **Manage keys**.
1. In the **Keys** tab, click **Add Key** > **Create new key**.
1. Select **JSON** as the key type and click **Create**. Save the downloaded JSON key file for later use.

Upload this JSON key file when configuring your Firebase App Distribution destination in the Capawesome Cloud Console.

### Publishing Format

Both Android App Bundles (AAB) and APKs are supported. **AAB uploads require your Firebase app to be linked to Google Play.** That's why the Console preselects APK for Android destinations. If your Firebase app isn't linked to Google Play, keep APK.

If your build contains a Wear OS, Android TV, or Automotive module, only the phone app is uploaded. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

## Release Notes

Firebase App Distribution shows testers the default text of a deployment's [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md), up to 4,000 characters. Firebase doesn't support translations, so they're ignored. Release notes are optional.

## iOS Builds

Testers can only install iOS builds of type [Ad Hoc, Development, or Enterprise](https://capawesome.io/docs/cloud/native-builds/build-types/#ios-build-types). App Store builds can't be installed by testers, so submitting one to this destination fails.

For Ad Hoc and Development builds, the UDIDs of your testers' devices must be included in the [provisioning profile](https://capawesome.io/docs/cloud/native-builds/certificates/ios/#provisioning-profiles). Firebase collects the UDIDs of your testers and sends them to you by email. Register the devices in your Apple Developer account, regenerate the provisioning profile, and replace it in your signing certificate before the next build.

## Next steps

- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — send a build to your new destination.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — distribute every build with an automation.

# Google Play

To submit your Android app builds to Google Play, you need to configure a Google Play destination in the Capawesome Cloud Console. App submissions are uploaded to the specified track for testing and distribution.

AI-Assisted Setup

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill capawesome-cloud` and use the following prompt with your preferred AI coding assistant:

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up a Google Play destination in Capawesome Cloud.
```

Initial Upload Requirement

The very first version of your app **must be uploaded manually** to Google Play Console. Subsequent builds can then be submitted automatically via Capawesome Cloud. This is not a limitation of Capawesome Cloud, but a requirement from Google Play.

## Configuration

To create a Google Play destination, navigate to the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for this destination (e.g., "Production Android", "Beta Release").
- **Platform**: Must be set to `Android`.
- **Type**: Must be set to `Google Play`.
- **Track**: The release track (`Internal`, `Alpha`, `Beta`, or `Production`).
- **Package name**: Your Android application ID / package name (e.g., `com.example.app`).
- **Publishing format**: The app bundle format (`AAB` or `APK`).
- **Release status**: The release status (`Draft` or `Completed`).
- **JSON Key File**: Service account JSON key file from Google Play Console.
- **Default language**: The language of the default [release notes](#release-notes) text (optional, e.g., `en-US`).

Read on for detailed instructions on obtaining the required credentials.

## Obtaining Credentials

### Package Name

The package name (also called application ID) is defined in your Android app's `build.gradle` file. It typically follows the format `com.example.app` and uniquely identifies your application on Google Play.

### Track

Choose the appropriate release track for your submissions:

- **Internal**: For internal testing with a small group of trusted testers.
- **Alpha**: For early testing with a limited audience.
- **Beta**: For broader testing before production release.
- **Production**: For public release to all users.

#### Form Factors

If your build contains a Wear OS, Android TV, or Automotive module, the selected track applies to the phone app. The other artifacts are published to Google Play's prefixed track of the same name: `wear:<track>`, `tv:<track>`, and `automotive:<track>`. A destination with the track `Production` therefore publishes the watch app to `wear:production`.

Before the first submission, enable the form factor in Google Play Console under **Advanced settings → Form factors**. Google Play only offers the prefixed tracks after this opt-in. Each artifact also needs a version code that is unique across form factors. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

### Publishing Format

Both Android App Bundles (AAB) and APKs are supported. The **Android App Bundle is the required format** for new apps on Google Play, while APKs can still be used for existing apps. We recommend AAB for all apps: downloads are smaller, and with R8/ProGuard enabled, Google Play deobfuscates crash reports automatically. See [Publish Android App Bundles](https://capawesome.io/docs/cloud/native-builds/android-app-bundles/index.md).

A submission uploads every artifact of the build in the selected format, so a project with several application modules publishes all of them at once.

### Release Status

The release status determines how your app is published to the selected track:

- **Draft**: Choose this for initial releases that require manual review before publishing. This is useful for the very first release of your app on a track, where you may need to complete additional setup steps in Google Play Console.
- **Completed**: Choose this for releases that should be automatically published in the selected track. This is the typical choice for subsequent releases after your initial setup is complete.

### JSON Key File

A service account JSON key file is required to authenticate with Google Play Console.

Tip

If you see Google Play Console or Google Cloud Console in your local language, add `?hl=en` to the end of the URL to switch to English.

To obtain the service account JSON key file:

1. Sign in to [Google Cloud Console](https://console.cloud.google.com/).
1. Navigate to **IAM & Admin** > **Service Accounts**.
1. Create a new service account by clicking **Create Service Account**.
1. In step 1, fill in the service account details and click **Create and Continue**.
1. In step 2, assign the role **Service Account User** and click **Continue**.
1. In step 3, you can leave the fields empty and click **Done**.
1. In the list of service accounts, locate the newly created service account. Copy its **email address**, which will be required later. Then, click on the menu in the Actions column and select **Manage keys**.
1. In the **Keys** tab, click **Add Key** > **Create new key**.
1. Select **JSON** as the key type and click **Create**. Save the downloaded JSON key file for later use.
1. Sign in to [Google Play Console](https://play.google.com/console).
1. Navigate to **Users and Permissions** and click **Invite new user**. Enter the email address which you copied in step 4.
1. Go to the **App permissions** tab. Add the desired applications to grant access to.
1. This will open a dialog where you can select the required permissions. Make sure to check at least all permissions in the **Release** section, then click **Apply**.
1. Finally, click **Invite User** to finish setting up the service account.

Upload this JSON key file when configuring your Google Play destination in the Capawesome Cloud Console.

## Release Tracks

After submission, your app will be available on the selected track in Google Play Console. You can manage releases, view analytics, and promote builds to higher tracks (e.g., from beta to production) directly in Google Play Console.

## Release Notes

[Release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) of a deployment become **What's new** of the track release, up to 500 characters per language. The default text is published in the destination's **Default language**, or in `en-US` if none is set, and each translation in its own language. A build with a Wear OS, Android TV, or Automotive module publishes the same release notes to every track it's released to. Release notes are optional: without them, Capawesome Cloud doesn't set **What's new**.

Set the default language to the default language of your store listing if it isn't `en-US`:

```
npx @capawesome/cli apps:destinations:update --app-id <app-id> --destination-id <destination-id> --default-language de-DE
```

Open the destination on the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page and enter the language in **Default language**.

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers setting up a Google Play destination end to end:

## Next steps

- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — send a build to your new destination, with release notes.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — submit every release with an automation.

# Huawei AppGallery

To submit your Android app builds to Huawei AppGallery, you need to configure a Huawei AppGallery destination in the Capawesome Cloud Console. App submissions are uploaded to AppGallery Connect and, depending on the release status, submitted for review.

## Configuration

To create a Huawei AppGallery destination, navigate to the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for this destination (e.g., "AppGallery Production").
- **Platform**: Must be set to `Android`.
- **Type**: Must be set to `Huawei AppGallery`.
- **App ID**: Your AppGallery Connect app ID (e.g., `112233445`).
- **Client ID**: The client ID of your AppGallery Connect API client.
- **Client secret**: The client secret of your AppGallery Connect API client.
- **Publishing format**: The app bundle format (`AAB` or `APK`).
- **Release status**: The release status (`Draft` or `Completed`).
- **Default language**: The language of the default [release notes](#release-notes) text (optional, e.g., `en-US`).

Read on for detailed instructions on obtaining the required credentials.

## Obtaining Credentials

### App ID

The app ID is the numeric identifier of your app in AppGallery Connect. Create your app in [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html) if you haven't already, then copy the app ID from the app's details.

### Client ID and Client Secret

Capawesome Cloud authenticates with the AppGallery Connect Publishing API using an API client. In AppGallery Connect, create an API client for the AppGallery Connect API with permission to publish apps, then copy its client ID and client secret.

The client secret is stored encrypted and is never shown again after you save the destination.

### Publishing Format

Both Android App Bundles (AAB) and APKs are supported. After the upload, AppGallery Connect processes every package, for example by compiling an AAB and running a security check. Capawesome Cloud waits for this processing to finish before the deployment completes, whatever the release status, so a deployment can take several minutes.

If your build contains a Wear OS, Android TV, or Automotive module, only the phone app is uploaded. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

### Release Status

The release status determines what happens after the upload:

- **Draft**: The build is only uploaded to AppGallery Connect. Choose this if you want to review the version and submit it for review manually in AppGallery Connect.
- **Completed**: The build is uploaded and, once AppGallery Connect has finished processing it, the version is submitted for review automatically.

## Release Notes

[Release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) of a deployment become **New features** of the app version in AppGallery Connect, up to 500 characters per language. Capawesome Cloud sets them once AppGallery Connect has processed the package, before the version is submitted for review. The default text is published in the destination's **Default language**, or in `en-US` if none is set, and each translation in its own language. Release notes are optional: without them, Capawesome Cloud doesn't change **New features**.

Set the default language to the default language of your app in AppGallery Connect if it isn't `en-US`:

```
npx @capawesome/cli apps:destinations:update --app-id <app-id> --destination-id <destination-id> --default-language de-DE
```

Open the destination on the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page and enter the language in **Default language**.

## Common Issues

### Submission fails because a version is under review

AppGallery Connect doesn't accept a new submission while another version of your app is under review. Capawesome Cloud doesn't withdraw that version automatically, so the deployment fails with the error message returned by Huawei. Withdraw the version under review in AppGallery Connect, then submit the build again.

## Next steps

- [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — send a build to your new destination.
- [Submit automatically after a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-automatically/index.md) — submit every release with an automation.

# Cloud Assist

**Capawesome Cloud Assist** is the AI surface inside the [Capawesome Cloud](/) Console. Cloud Assist features sit next to the work they help with — failed builds, deployments, and more — so you don't have to leave the dashboard to get answers.

Cloud Assist is currently **experimental**. Features are marked with a "New" badge in the Console and are rolled out gradually based on usage and feedback. Cloud Assist is included free in all [Capawesome Cloud plans](https://capawesome.io/pricing/) that include build minutes.

## Features

- ✨ **AI-Powered Diagnoses**: One-click summaries of failed builds and deployments with cause, explanation, and suggested fix.
- 🔒 **Privacy by Design**: Only the data needed for each feature is sent to the AI provider, with zero data retention.
- 👥 **Permission-Gated**: Mirrors existing organization permissions — only members with write access can trigger AI features.
- 🆓 **Free**: Included in all Capawesome Cloud plans with build minutes.

## Documentation

- **Ask AI**

  ______________________________________________________________________

  Diagnose failed builds and deployments with one click.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/assist/ask-ai/index.md)

- **FAQ**

  ______________________________________________________________________

  Find answers to frequently asked questions about Cloud Assist.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/assist/faq/index.md)

# Ask AI

**Ask AI** is the first feature in [Capawesome Cloud Assist](https://capawesome.io/docs/cloud/assist/index.md). On any failed build or deployment, click the **Ask AI** button to get a structured summary of what went wrong and a suggested fix — without leaving the [Capawesome Cloud](/) Console.

## How It Works

On a failed build or deployment, members with write access see an **Ask AI** button (sparkles icon, "New" badge) in the toolbar.

1. Open the failed build or deployment in the [Capawesome Cloud Console](https://console.cloud.capawesome.io).
1. Click **Ask AI**.
1. A consent dialog explains what data is shared. Click **Generate**.
1. After a few seconds, a markdown summary appears in the dialog with three sections:
   - **Cause** — the line(s) that actually broke the job.
   - **Explanation** — why it broke, in plain English.
   - **Suggested fix** — a concrete next step, often with a `bash` snippet.
1. Click **Copy** to put the raw markdown on your clipboard. Paste it into a PR description, ticket, Slack message, or as context into a local AI coding agent like [Claude Code](https://www.anthropic.com/claude-code) or [Cursor](https://www.cursor.com/) to apply the fix directly to your codebase.

## Anatomy of a Result

Every Ask AI response has the same three sections, rendered as markdown in the dialog and available verbatim via the **Copy** button.

Sample result

**Cause**

`android/app/build.gradle:42` — Could not resolve `com.google.firebase:firebase-bom:33.0.0`.

**Explanation**

Your Android build failed because Gradle could not download the `firebase-bom` artifact at version `33.0.0` from any configured Maven repository. This usually means the version doesn't exist yet, was renamed, or your `repositories` block is missing Google's Maven repo.

**Suggested fix**

Pin `firebase-bom` to a published version and confirm `google()` is listed under `repositories` in `android/build.gradle`.

```
implementation platform('com.google.firebase:firebase-bom:32.7.0')
```

The output is capped at around 400 words to keep the result a summary rather than a wall of text. Code snippets are formatted as fenced code blocks so they paste cleanly into PRs, tickets, or chat.

## Workflow Integrations

Ask AI's output is plain markdown by design. A few patterns work well:

- **Paste into a PR description.** When the failure prompted a fix, dropping the diagnosis into the PR body gives reviewers the full context without making them re-read the logs. Renders correctly in GitHub, GitLab, Bitbucket, and Azure DevOps.
- **Hand off to a local AI coding agent.** Paste the diagnosis as context into [Claude Code](https://www.anthropic.com/claude-code), [Cursor](https://www.cursor.com/), or any other agent. The agent now has the exact cause and suggested fix, and can apply the change directly to your codebase.
- **Async debugging via shared cache.** When someone links to a failed build in chat or a stand-up, anyone with permission sees the same cached diagnosis instantly — no duplicate AI runs, no inconsistent answers across teammates.

# FAQ

## General

### What is Capawesome Cloud Assist?

[Cloud Assist](https://capawesome.io/docs/cloud/assist/index.md) is the AI surface inside the [Capawesome Cloud](/) Console. It groups all AI-powered features under a single name, starting with [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md) for failed builds and deployments.

### What's the difference between Cloud Assist and Ask AI?

**Cloud Assist** is the umbrella product. **Ask AI** is the first feature shipping under it. More features will be added over time.

### Is Cloud Assist available on all plans?

Cloud Assist is included free in every [Capawesome Cloud plan](https://capawesome.io/pricing/) that includes build minutes. Plans without build minutes don't include Cloud Assist, since the feature operates on build and deployment logs.

### Does Cloud Assist work for non-Capacitor projects?

Yes. Cloud Assist works across all project types supported by Capawesome Cloud — Capacitor, Cordova, native iOS, and native Android.

## Ask AI

### What data is sent to the AI provider?

Only the build logs of the specific failed job. No source code, no environment variables, no project metadata, and no other jobs are sent.

### Is my data used to train AI models?

No. Our AI provider does not retain or train on the data sent through Cloud Assist.

### Who can use Ask AI?

Only members of the organization with **write access to the app** can trigger Ask AI. This mirrors the permissions that already control builds and deployments. See [Roles and Permissions](https://capawesome.io/docs/cloud/organizations/memberships/#roles-and-permissions) for details.

### Are results cached?

Yes. The first teammate to click **Ask AI** on a failed job triggers the run, and the result is cached against that job and shared across the organization. Every other member with permission opens the dialog and sees the same answer instantly.

### Why is Ask AI marked as experimental?

Ask AI is shipping as a beta. Quality, latency, and UX will continue to iterate based on real usage and feedback. The "New" badge in the Console signals this.

### Can the AI's answer be wrong?

Yes. Like any AI-generated content, the diagnosis can be incorrect or incomplete. Always verify the suggested fix before applying it.

### Why is the output capped at around 400 words?

To keep the result a summary that's quick to read, copy, and paste — rather than a wall of text you'd have to re-read the logs to verify.

### Can I regenerate the answer or ask follow-up questions?

Not yet. The current version returns a single response. Regenerate-with-context and follow-up questions are on the roadmap.

### Does Ask AI work on succeeded builds?

No. The **Ask AI** button only appears on failed builds and deployments.

# Automations

Use [Capawesome Cloud](/) to automatically trigger builds when you push to a branch or create a tag. Set up an automation once and every matching Git event will kick off a build — no manual steps needed.

## Features

- ⚡ **Git-Triggered Builds**: Automatically start builds when you push to a branch or create a tag.
- 🎯 **Pattern Matching**: Target specific branches or tags using name patterns.
- 💬 **Commit Message Filtering**: Optionally filter triggers based on the commit message content.
- 📱 **Multi-Platform**: Configure automations per platform — Android, iOS, or Web.
- ⚙️ **Build Settings**: Attach a signing certificate, environment, destination, or channel to each automation.
- 🚫 **Skip CI**: Skip automations for specific commits by adding `[skip ci]` to the commit message.
- 🔀 **Enable/Disable**: Toggle automations on or off without deleting them.

## Getting Started

- **Setup Automations**

  ______________________________________________________________________

  Create your first automation with Capawesome Cloud.

  ______________________________________________________________________

  [Getting Started](https://capawesome.io/docs/cloud/automations/setup/index.md)

## Documentation

- **Manage Automations**

  ______________________________________________________________________

  Create, edit, enable, and disable automations for your app.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/manage-automations/index.md)

- **Trigger on Branch Pushes**

  ______________________________________________________________________

  Start a build whenever you push to a matching branch.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/trigger-on-branch-pushes/index.md)

- **Trigger on Tags**

  ______________________________________________________________________

  Start a build whenever you create a matching tag.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/trigger-on-tags/index.md)

- **Filter by Commit Message**

  ______________________________________________________________________

  Trigger builds only for commits matching a pattern.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/index.md)

- **Attach Build Settings**

  ______________________________________________________________________

  Attach a certificate, environment, destination, or channel.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md)

- **Auto-Publish a Live Update**

  ______________________________________________________________________

  Publish a live update automatically after a build.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md)

- **Auto-Submit to a Store**

  ______________________________________________________________________

  Submit a build to a store automatically after it completes.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/auto-submit/index.md)

- **Webhooks**

  ______________________________________________________________________

  Learn how to configure webhooks for your automations.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/webhooks/index.md)

- **Reference**

  ______________________________________________________________________

  Look up all available automation settings and options.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/reference/index.md)

- **Troubleshooting**

  ______________________________________________________________________

  Find solutions to common automation issues.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/troubleshooting/index.md)

- **FAQ**

  ______________________________________________________________________

  Find answers to frequently asked questions about Automations.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/automations/faq/index.md)

# Attach Build Settings

A triggered build is just a build — so it takes the same settings a manual build does. Attaching them to the automation means every build it kicks off is configured exactly how you want, with nothing to set per release.

| Setting                  | Description                                                                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Build type**           | The [type of build](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) to create.                                                                                                                                               |
| **Build stack**          | The [build stack](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md) to build on. If unset, builds use the app's default build stack, or Capawesome Cloud's default build stack if the app has none.                           |
| **Signing certificate**  | The [certificate](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) to sign the build with.                                                                                                                                   |
| **Native configuration** | The [native configuration](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md) to build with.                                                                                                                          |
| **Environment**          | The [environment](https://capawesome.io/docs/cloud/native-builds/environments/index.md) (variables and secrets) for the build.                                                                                                                    |
| **Store destination**    | A [store destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) to submit the build to — see [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md).                      |
| **Channels**             | One or more [Live Update channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) to publish a web build to — see [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md). |

A few settings are tied to the platform you picked: **Channels** apply to **Web** automations, while a **Store destination**, **Signing certificate**, **Native configuration**, and **Build type** apply to the **Android** and **iOS** builds you submit to the stores.

## From a build to a pipeline

Most settings shape the build itself, but **Store destination** and **Channels** go one step further — they tell the automation what to do *after* the build succeeds. Attach one and the automation becomes a full pipeline: Git event → build → submit or publish, with no manual steps in between.

## Next steps

- [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) — attach a destination for a build-and-submit pipeline.
- [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) — attach channels for an over-the-air pipeline.
- [Automations reference](https://capawesome.io/docs/cloud/automations/reference/#build-settings) — every build-settings field at a glance.

# Auto-Publish a Live Update

Attach one or more [Live Update channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) to an automation and it will build your web assets and **publish a Live Update** automatically — a Git → web build → over-the-air update pipeline. Push your change, and devices pick it up on their next launch without an app store release.

## Set it up

1. Make sure your app is set up for [Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/index.md).
1. Create an [automation](https://capawesome.io/docs/cloud/automations/trigger-on-branch-pushes/index.md) with the trigger you want — for example, a push to `main`.
1. Set the **Platform** to **Web**.
1. In the automation's [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md), select the **Channels** to publish to.

Now every matching push builds your web assets in the cloud and publishes a Live Update to the selected channels, which devices pick up on their next launch.

Keep updates compatible

A Live Update can only change your web layer, so it must stay compatible with the installed native binary. Publish to a [versioned channel](https://capawesome.io/docs/cloud/live-updates/setup/#make-updates-version-compatible) so updates only ever reach native versions that can run them — see [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for why this matters.

## Publish to multiple channels

To ship the same web build to several channels, select each of them in the **Channels** field, or repeat the `--channel` option when you create the automation with the CLI:

```
npx @capawesome/cli apps:automations:create \
  --name web-release \
  --platform web \
  --trigger-type branch \
  --trigger-pattern main \
  --channel production \
  --channel staging
```

## Next steps

- [Publish a Live Update](https://capawesome.io/docs/cloud/live-updates/publish/index.md) — how publishing works when you do it by hand.
- [Trigger on branch pushes](https://capawesome.io/docs/cloud/automations/trigger-on-branch-pushes/index.md) — the recommended trigger for continuous web releases.
- [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) — the native-app equivalent for store releases.

# Auto-Submit to a Store

Attach a [store destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) to an automation and it will build **and submit** your app automatically — a complete Git → build → store pipeline that ends with the build on TestFlight, a Google Play track, Huawei AppGallery, or Firebase App Distribution, without a single manual upload.

## Set it up

1. Create a [store destination](https://capawesome.io/docs/cloud/app-store-publishing/index.md) (App Store Connect, Google Play, Huawei AppGallery, or Firebase App Distribution).
1. Create an [automation](https://capawesome.io/docs/cloud/automations/trigger-on-tags/index.md) — tags (`v*`) are a natural fit for releases.
1. In the automation's [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md), select the **Store destination**.

Now every matching tag (or branch push) builds your app and submits the artifact to the destination — to TestFlight for Apple, the configured track for Google Play, AppGallery Connect for Huawei, or your tester groups for Firebase.

Pair with signing

Store submissions require a signed build. Attach the matching [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) to the same automation so the triggered build is signed correctly.

No release notes

Automations can't provide [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md), so their submissions leave the release notes in the store unchanged. An App Store Connect destination with [beta groups](https://capawesome.io/docs/cloud/app-store-publishing/submit-for-app-review/#distribute-to-beta-groups) requires release notes, so don't attach one to an automation: its deployments fail with "No changelog provided". Submit such builds with the CLI instead.

## What happens after submission

The automation's job ends once the build is submitted. The stores then run their own processing and review, so a finished submission means the build *reached* the store — not that it's live yet. Track the result on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page, just like a manual submission. See [Submit a Build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/#after-submitting) for what each store does next.

## Next steps

- [Submit a Build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) — how submissions work and how to track them.
- [Trigger on tags](https://capawesome.io/docs/cloud/automations/trigger-on-tags/index.md) — the recommended trigger for releases.
- [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) — the over-the-air equivalent for web builds.

# FAQ

### What can trigger an automation?

A push to a matching branch, or the creation of a matching tag. You can also filter by [commit message](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/index.md).

### Which Git providers are supported?

GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea. [Git (HTTP/S)](https://capawesome.io/docs/cloud/integrations/git/index.md) connections don't support webhooks, so Automations aren't available for them. See [Integrations](https://capawesome.io/docs/cloud/integrations/index.md).

### How do I skip a build for a specific commit?

Add a [skip keyword](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/#skip-keywords) such as `[skip ci]` to the head commit message.

### Can an automation also submit to a store or publish a Live Update?

Yes — attach a [destination](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) or a [channel](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) to the automation.

### My automation didn't run — what should I check?

See [Troubleshooting](https://capawesome.io/docs/cloud/automations/troubleshooting/index.md).

# Filter by Commit Message

A trigger pattern decides *which branch or tag* builds; a commit-message filter decides *whether a given push* builds at all. It's the tool you reach for when matching the branch isn't enough — to skip builds for documentation-only changes, or to build only when a message opts in.

There are two ways to filter: a positive pattern that the message must match, and skip keywords that suppress a build.

## Commit message pattern

When creating an automation, set an optional **Commit message pattern**. The automation then only triggers when the head commit message matches the pattern — useful when you want builds reserved for specific commits, such as those tagged `[build]` or following a release-commit convention.

## Skip keywords

To skip an automation for a specific push, include one of these keywords anywhere in the **head commit** message (case-insensitive):

- `[skip ci]`
- `[ci skip]`
- `[skip capawesome]`
- `[capawesome skip]`

For example:

```
docs: update readme [skip ci]
```

This is handy for commits that don't change the app itself — documentation, configuration, or chores — so you don't spend build minutes on them.

Only the head commit is checked

Capawesome Cloud only inspects the head commit (the latest commit in the push), not every commit in the range.

## Next steps

- [Trigger on branch pushes](https://capawesome.io/docs/cloud/automations/trigger-on-branch-pushes/index.md) — the automation a filter refines.
- [Automations reference](https://capawesome.io/docs/cloud/automations/reference/#skip-keywords) — the full list of patterns and keywords.

# Manage Automations

Once an automation exists, you can manage it from the CLI or from the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page in the Console. Each automation lists its trigger, its patterns, and when it **Last triggered**, so you can see at a glance what's active and what's recently run.

## Inspect automations

List every automation with [`apps:automations:list`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationslist), and inspect a single one with [`apps:automations:get`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationsget):

```
npx @capawesome/cli apps:automations:list

npx @capawesome/cli apps:automations:get --name nightly
```

Both commands accept `--json`, which makes them easy to pipe into other tools in a pipeline.

Open the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page of your app to see every automation, its trigger, and its **Last triggered** timestamp.

Names are unique per app and compared case-insensitively, so `Nightly` and `nightly` are the same name.

## Edit an automation

Update a trigger, a pattern, or any [build setting](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md) with [`apps:automations:update`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationsupdate):

```
npx @capawesome/cli apps:automations:update \
  --automation-id 12345678-1234-1234-1234-123456789012 \
  --trigger-pattern "release/*" \
  --environment staging
```

Updates are addressed by ID — use `apps:automations:get --name nightly --json` to look one up. `--name` sets a new name instead of selecting the automation. Repeat `--trigger-pattern` to set more than one pattern.

Pass an empty string to clear a value again — `--environment ""` detaches the environment, `--commit-message-pattern ""` removes the commit filter, and `--trigger-pattern ""` removes all trigger patterns.

Click **Edit** on the automation and update its trigger, patterns, or [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md).

## Delete an automation

Remove an automation with [`apps:automations:delete`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationsdelete):

```
npx @capawesome/cli apps:automations:delete --name nightly
```

Add `--yes` to skip the confirmation prompt in a pipeline.

Click **Delete** on the automation and confirm the deletion.

Deleting an automation also removes the webhook it registered on your repository.

## Enable, disable, and history

Two actions are available in the Console only:

- **Enable / Disable** — toggle an automation on or off without deleting it. A disabled automation stays configured but doesn't trigger builds, which is handy during a code freeze or while you debug a pipeline.
- **History** — review the builds an automation has triggered, so you can trace a build back to the push that started it.

To temporarily stop builds for a single push without disabling anything, use a [skip keyword](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/#skip-keywords) in your commit message instead.

## Next steps

- [Filter by commit message](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/index.md) — skip individual pushes without touching the automation.
- [Troubleshooting](https://capawesome.io/docs/cloud/automations/troubleshooting/index.md) — what to check when an automation doesn't run.
- [Automations reference](https://capawesome.io/docs/cloud/automations/reference/index.md) — trigger patterns, skip keywords, and build settings.

# Reference

## Trigger pattern syntax

An automation can have up to 10 trigger patterns. Patterns match the full branch or tag name using glob wildcards:

| Pattern      | Matches                                                |
| ------------ | ------------------------------------------------------ |
| `main`       | the `main` branch exactly                              |
| `v*`         | tags like `v1.0.0`, `v2.3.4`                           |
| `release/*`  | branches like `release/1.0`, `release/2.0`             |
| `release/**` | branches like `release/1.0` and `release/hotfix/1.0.1` |
| `!v*-*`      | excludes tags like `v1.0.0-rc.1`                       |
| `*`          | any branch or tag without a `/` in its name            |

`*` matches any characters except `/`, `**` matches any characters including `/`, and a pattern starting with `!` excludes the names it matches.

### Combining patterns

A branch or tag triggers the automation when no exclude pattern matches it and either no other pattern is set or at least one of them matches. An automation without any pattern therefore runs for every branch or tag of its trigger type.

For example, the patterns `v*` and `!v*-*` match `v1.0.0` but not `v1.0.0-rc.1` or `v1.0.0-prod.1`.

## Skip keywords

Include any of these in the **head commit** message to skip an automation (case-insensitive):

- `[skip ci]`
- `[ci skip]`
- `[skip capawesome]`
- `[capawesome skip]`

## Build settings

| Setting              | CLI option        | Description                                                                                                                                                                                     |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Platform             | `--platform`      | Android, iOS, or Web                                                                                                                                                                            |
| Build Type           | `--type`          | The [build type](https://capawesome.io/docs/cloud/native-builds/build-types/index.md)                                                                                                           |
| Build Stack          | `--stack`         | The [build stack](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md); if unset, the app's default build stack, or Capawesome Cloud's default build stack if the app has none |
| Signing Certificate  | `--certificate`   | The [certificate](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) to sign with                                                                                            |
| Native Configuration | `--configuration` | The [native configuration](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md) to build with                                                                         |
| Environment          | `--environment`   | The [environment](https://capawesome.io/docs/cloud/native-builds/environments/index.md) (variables/secrets)                                                                                     |
| Store Destination    | `--destination`   | A [store destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) to submit to                                                                                 |
| Live Update Channels | `--channel`       | One or more [Live Update channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) to publish to                                                                               |

The CLI options apply to [`apps:automations:create`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationscreate) and [`apps:automations:update`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationsupdate). The certificate, native configuration, environment, store destination, and Live Update channels are referenced by name rather than by ID.

# Getting Started

In this guide, you will learn how to create your first automation using Capawesome Cloud.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
- An app created in the console (see [Getting Started with Native Builds](https://capawesome.io/docs/cloud/native-builds/setup/index.md)).
- A Git repository connected to the app (see [Connect Git Repository](https://capawesome.io/docs/cloud/native-builds/setup/#step-2-connect-git-repository)).
- A Git provider account linked (see [Integrations](https://capawesome.io/docs/cloud/integrations/index.md)).
- An organization plan with build minutes.

## Step 1: Create an Automation

Create an automation with the [`apps:automations:create`](https://capawesome.io/docs/cloud/cli/commands/#appsautomationscreate) command:

```
npx @capawesome/cli apps:automations:create \
  --name nightly \
  --platform android \
  --trigger-type branch \
  --trigger-pattern main
```

Repeat `--trigger-pattern` to add more patterns.

Run the command without options to be guided through the required values interactively.

Navigate to the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page of your app in the Capawesome Cloud Console, click on the **Create automation** button, and configure the following properties:

- **Name**: A display name to identify the automation.
- **Platform**: The target platform — Android, iOS, or Web.
- **Trigger type**: The Git event that triggers the build — **Branch** (triggers on push to a branch) or **Tag** (triggers on tag creation).
- **Trigger patterns**: The branch or tag names to match. For example, `main` to trigger on pushes to the `main` branch, or `v*` to trigger on tags starting with `v`. A pattern starting with `!` excludes the names it matches, such as `!v*-*` for pre-release tags.
- **Commit message pattern** (optional): A pattern to filter triggers based on the commit message content.

## Step 2: Configure Build Settings (Optional)

You can optionally configure additional build settings for the automation:

Pass the build settings as options — signing certificates, environments, native configurations, store destinations, and Live Update channels are referenced by name:

```
npx @capawesome/cli apps:automations:create \
  --name release \
  --platform ios \
  --trigger-type tag \
  --trigger-pattern "v*" \
  --type app-store \
  --certificate "Distribution" \
  --environment production \
  --destination "TestFlight"
```

Repeat `--trigger-pattern` to add more patterns — for example `--trigger-pattern 'v*' --trigger-pattern '!v*-*'` to skip pre-release tags like `v1.0.0-rc.1`.

Configure the build settings in the **Create automation** dialog:

- **Build type**: The type of build to create (see [Build Types](https://capawesome.io/docs/cloud/native-builds/build-types/index.md)).
- **Build stack**: The build stack to use (see [Build Stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md)). Disable **Use the app's default build stack** to pin one. Otherwise builds use the app's default build stack, or Capawesome Cloud's default build stack if the app has none.
- **Signing certificate**: The signing certificate for the build (see [Signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md)).
- **Environment**: The environment variables for the build (see [Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md)).
- **Store destination**: The publish destination for the build artifact (see [Store destinations](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md)).
- **Channels**: The Live Update channels to deploy to (see [Channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md)).

## Step 3: Verify Webhook Setup

When you create an automation, Capawesome Cloud automatically registers a webhook on your connected Git repository. This webhook listens for the configured Git events and triggers builds accordingly.

If automatic registration fails, you can configure the webhook manually. See [Webhooks](https://capawesome.io/docs/cloud/automations/webhooks/index.md) for instructions.

## Step 4: Test the Automation

Push a commit or create a tag that matches your trigger pattern and verify that:

1. The automation's **Last triggered** timestamp updates on the Automations page.
1. A new build appears on the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page.

Congratulations! You have successfully created your first automation using Capawesome Cloud. 🎉

## Managing Automations

After creating an automation, you can manage it from the Automations page:

- **Edit**: Update the automation's configuration by clicking on the **Edit** button.
- **Enable/Disable**: Toggle an automation on or off without deleting it. Disabled automations do not trigger builds.
- **History**: View the build history for a specific automation by clicking on the **History** button.
- **Delete**: Remove an automation by clicking on the **Delete** button and confirming the deletion.

Listing, editing, and deleting automations also work from the CLI. See [Manage Automations](https://capawesome.io/docs/cloud/automations/manage-automations/index.md).

## Skipping Automations

You can skip automations for a specific push by including one of the following keywords in the **head commit** message:

- `[skip ci]`
- `[ci skip]`
- `[skip capawesome]`
- `[capawesome skip]`

The keyword check is **case-insensitive** and can appear anywhere in the commit message. For example:

```
docs: update readme [skip ci]
```

This is useful for documentation-only changes or other commits that don't require a build.

Note

Only the head commit message (i.e. the latest commit in the push) is checked.

## Next Steps

- **Attach Build Settings**

  ______________________________________________________________________

  Sign and configure the builds your automation triggers.

  [Attach build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md)

- **Auto-Submit to a Store**

  ______________________________________________________________________

  Build and submit to TestFlight or Google Play on every tag.

  [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md)

- **Auto-Publish a Live Update**

  ______________________________________________________________________

  Build and ship an over-the-air update on every push.

  [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md)

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers creating your first automation from start to finish:

# Trigger on Branch Pushes

A branch automation starts a build every time you push to a matching branch. It's the right choice for continuous builds — for example, a fresh QA build on every push to `main`, or a build for each of your `release/*` branches — so the latest code is always built without anyone clicking a button.

## Create the automation

1. Open the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page and click **Create automation**.
1. Set the **Trigger type** to **Branch**.
1. Set the **Trigger patterns** to the branch names to match. A pattern can be an exact name like `main`, a glob like `release/*` to match every release branch, or a pattern starting with `!` to exclude branches. See the [pattern syntax](https://capawesome.io/docs/cloud/automations/reference/#trigger-pattern-syntax) for all options.
1. Choose the **Platform** (Android, iOS, or Web) and any [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md).

Every push to a matching branch now starts a build. Capawesome Cloud registers a webhook on your repository automatically — see [Set up the Git webhook](https://capawesome.io/docs/cloud/automations/webhooks/index.md) if you ever need to configure it manually.

## Narrow down which pushes build

Branches can be busy, and you won't want a build for every commit. To skip some pushes, add a [commit-message filter](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/index.md) — for example, to skip documentation-only commits with `[skip ci]`, or to build only when the message matches a pattern.

## Next steps

- [Attach build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md) — sign, configure, and target the triggered builds.
- [Filter by commit message](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/index.md) — control exactly which pushes build.
- [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) — turn a branch automation into an over-the-air release pipeline.

# Trigger on Tags

Tag automations are ideal for releases: you cut a tag, and Capawesome Cloud builds — and optionally submits — the release automatically. Because a tag marks a deliberate point in your history, it maps neatly onto "this is the version we want to ship," which keeps release builds separate from the day-to-day branch builds.

## Create the automation

1. Open the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page and click **Create automation**.
1. Set the **Trigger type** to **Tag**.
1. Set the **Trigger patterns** to match your release tags — for example `v*` to match `v1.0.0`, `v1.2.3`, and so on. To skip pre-release tags such as `v1.0.0-rc.1`, add a second pattern `!v*-*`. See the [pattern syntax](https://capawesome.io/docs/cloud/automations/reference/#trigger-pattern-syntax) for more.
1. Choose the **Platform** and any [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md).

When you push a matching tag, Capawesome Cloud builds the exact commit the tag points to.

## Build a full release pipeline

A tag automation becomes a one-step release when you attach a publish target in its [build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md):

- Attach a [store destination](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) to submit the tagged build to TestFlight or Google Play.
- Attach a [Live Update channel](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) to publish a web build over the air.

## Next steps

- [Auto-submit to a store](https://capawesome.io/docs/cloud/automations/auto-submit/index.md) — build and submit releases from a tag.
- [Auto-publish a Live Update](https://capawesome.io/docs/cloud/automations/auto-publish-live-update/index.md) — ship web releases over the air.
- [Attach build settings](https://capawesome.io/docs/cloud/automations/attach-build-settings/index.md) — sign and configure the triggered builds.

# Troubleshooting

## My automation isn't triggering a build

Check these causes, roughly in order of likelihood:

1. **Pattern mismatch** — the pushed branch or tag doesn't match any of the automation's [trigger patterns](https://capawesome.io/docs/cloud/automations/reference/#trigger-pattern-syntax), or an exclude pattern (`!…`) matches it. Confirm the patterns (e.g. `v*` matches tags, not branches).
1. **Skip keyword** — the head commit message contains a [skip keyword](https://capawesome.io/docs/cloud/automations/filter-by-commit-message/#skip-keywords) like `[skip ci]`.
1. **Disabled** — the automation is toggled off. Check the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page.
1. **Webhook not registered** — if automatic webhook registration failed (insufficient permissions or a self-hosted provider), the Git event never reaches Capawesome Cloud. Configure it manually — see [Set up the Git webhook](https://capawesome.io/docs/cloud/automations/webhooks/index.md).
1. **No build minutes** — your plan's [build minutes](https://capawesome.io/docs/cloud/native-builds/limits/index.md) are exhausted.

## How do I confirm the webhook is working?

Push a commit or create a tag that matches the trigger pattern, then check that the automation's **Last triggered** timestamp updates and a new build appears on the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page. See [Set up the Git webhook](https://capawesome.io/docs/cloud/automations/webhooks/#verifying-the-webhook).

## A build was triggered but failed

That's a build problem, not an automation problem — see [Native Builds troubleshooting](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md).

# Webhooks

Automations use webhooks to receive Git events from your provider. When you create an automation, Capawesome Cloud automatically registers a webhook on your connected Git repository. If automatic registration fails, you can configure the webhook manually.

## Automatic Setup

When you create an automation, Capawesome Cloud attempts to register a webhook on your Git repository automatically. If the registration succeeds, no further action is needed — the webhook is ready to receive events.

## Manual Setup

In some cases, automatic webhook registration may fail — for example, due to insufficient permissions or when using a self-hosted Git provider. In these cases, you can configure the webhook manually using the values provided in the **Setup** dialog.

### Access the Setup Dialog

To access the Setup dialog, navigate to the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page of your app in the Capawesome Cloud Console and click the **Setup** button. The dialog displays two values:

- **Webhook URL**: The endpoint that receives Git events from your provider.
- **Webhook Secret**: A secret used to verify incoming webhook payloads.

Both values have copy-to-clipboard buttons for convenience.

### Configure Your Git Provider

Webhooks are registered automatically by Capawesome Cloud when you connect a repository through a [Git connection](https://capawesome.io/docs/cloud/integrations/index.md). Manual setup is only needed if automatic registration fails — add a new webhook in your Git provider's settings using the **Webhook URL** and **Webhook Secret** from the Setup dialog, configured to send push events.

Git (HTTP/S) connections

[Git (HTTP/S)](https://capawesome.io/docs/cloud/integrations/git/index.md) connections do not support webhooks, so Automations are not available for repositories connected this way.

## Verifying the Webhook

To confirm that the webhook is working correctly:

1. Push a commit or create a tag that matches one of your automation's trigger patterns.
1. Navigate to the [Automations](https://console.cloud.capawesome.io/apps/_/automations) page and check that the automation's **Last triggered** timestamp has updated.
1. Navigate to the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page and verify that a new build was created.

# CLI

The Capawesome Cloud CLI lets you manage your apps and resources straight from the command line — trigger [native builds](https://capawesome.io/docs/cloud/native-builds/index.md), publish [Live Updates](https://capawesome.io/docs/cloud/live-updates/index.md), submit to the [app stores](https://capawesome.io/docs/cloud/app-store-publishing/index.md), and manage channels, environments, and devices. It's the same API the Console uses, which makes it the natural fit for scripting and CI/CD pipelines.

## Quickstart

No installation required — run any command with `npx`. Log in, then run your first command:

```
npx @capawesome/cli login
npx @capawesome/cli apps:list
```

That's the whole loop — authenticate once, then call any `apps:<resource>:<action>` command. The pages below cover each step in more detail.

## Learn more

- [Installation](https://capawesome.io/docs/cloud/cli/installation/index.md) — install globally or run with `npx`, and pin a version for CI.
- [Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md) — log in interactively or with an API token.
- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — command anatomy, global flags, and JSON output.
- [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md) — every command and option.
- [Examples](https://capawesome.io/docs/cloud/cli/examples/index.md) — ready-to-use recipes for builds, Live Updates, and CI.
- [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) — automate the CLI in scripts and CI/CD pipelines.
- [Telemetry](https://capawesome.io/docs/cloud/cli/telemetry/index.md) — what the CLI collects and how to opt out.

# Authentication

Every command runs against your Capawesome Cloud account, so you need to authenticate before you can do anything useful. There are two ways to do it: an interactive login for your own machine, and an API token for automated environments.

## Interactive login

For local use, log in once. The CLI stores your credentials, so you stay logged in across commands and terminal sessions until you log out:

```
npx @capawesome/cli login
```

Confirm who you're logged in as at any time:

```
npx @capawesome/cli whoami
```

And log out to clear the stored credentials:

```
npx @capawesome/cli logout
```

## API tokens for CI/CD

Interactive login doesn't work on a build server, so in automated environments you authenticate with an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) instead. Create a token in Capawesome Cloud, store it as a secret in your CI provider, and pass it with `--token`:

```
npx @capawesome/cli login --token $CAPAWESOME_TOKEN
```

You can pass `--token` on `login` to authenticate for the rest of the session, or on an individual command to authenticate just that one call — handy when a pipeline runs a single command.

Keep tokens secret

Never hard-code a token or commit it to version control — always read it from a CI secret or environment variable, and rotate it if it might have leaked.

## Next steps

- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — global flags (including `--token`) and JSON output.
- [Examples](https://capawesome.io/docs/cloud/cli/examples/index.md) — CI recipes that authenticate with a token.
- [API tokens](https://capawesome.io/docs/cloud/accounts/tokens/index.md) — create and manage the tokens you authenticate with.

# Command Reference

Reference for every Capawesome Cloud CLI command. For installation, authentication, and general usage, see the [CLI overview](https://capawesome.io/docs/cloud/cli/index.md), [Installation](https://capawesome.io/docs/cloud/cli/installation/index.md), [Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md), and [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md).

- [`apps:create`](#appscreate)
- [`apps:delete`](#appsdelete)
- [`apps:get`](#appsget)
- [`apps:import`](#appsimport)
- [`apps:link`](#appslink)
- [`apps:list`](#appslist)
- [`apps:transfer`](#appstransfer)
- [`apps:unlink`](#appsunlink)
- [`apps:update`](#appsupdate)
- [`apps:automations:create`](#appsautomationscreate)
- [`apps:automations:delete`](#appsautomationsdelete)
- [`apps:automations:get`](#appsautomationsget)
- [`apps:automations:list`](#appsautomationslist)
- [`apps:automations:update`](#appsautomationsupdate)
- [`apps:builds:cancel`](#appsbuildscancel)
- [`apps:builds:create`](#appsbuildscreate)
- [`apps:builds:download`](#appsbuildsdownload)
- [`apps:builds:failure-summary`](#appsbuildsfailure-summary)
- [`apps:builds:get`](#appsbuildsget)
- [`apps:builds:list`](#appsbuildslist)
- [`apps:builds:logs`](#appsbuildslogs)
- [`apps:builds:run`](#appsbuildsrun)
- [`apps:builds:share`](#appsbuildsshare)
- [`apps:builds:unshare`](#appsbuildsunshare)
- [`apps:certificates:create`](#appscertificatescreate)
- [`apps:certificates:delete`](#appscertificatesdelete)
- [`apps:certificates:get`](#appscertificatesget)
- [`apps:certificates:list`](#appscertificateslist)
- [`apps:certificates:update`](#appscertificatesupdate)
- [`apps:channels:create`](#appschannelscreate)
- [`apps:channels:delete`](#appschannelsdelete)
- [`apps:channels:get`](#appschannelsget)
- [`apps:channels:list`](#appschannelslist)
- [`apps:channels:pause`](#appschannelspause)
- [`apps:channels:resume`](#appschannelsresume)
- [`apps:channels:update`](#appschannelsupdate)
- [`apps:configurations:create`](#appsconfigurationscreate)
- [`apps:configurations:delete`](#appsconfigurationsdelete)
- [`apps:configurations:get`](#appsconfigurationsget)
- [`apps:configurations:list`](#appsconfigurationslist)
- [`apps:configurations:update`](#appsconfigurationsupdate)
- [`apps:deployments:cancel`](#appsdeploymentscancel)
- [`apps:deployments:create`](#appsdeploymentscreate)
- [`apps:deployments:failure-summary`](#appsdeploymentsfailure-summary)
- [`apps:deployments:get`](#appsdeploymentsget)
- [`apps:deployments:list`](#appsdeploymentslist)
- [`apps:deployments:logs`](#appsdeploymentslogs)
- [`apps:destinations:create`](#appsdestinationscreate)
- [`apps:destinations:delete`](#appsdestinationsdelete)
- [`apps:destinations:get`](#appsdestinationsget)
- [`apps:destinations:list`](#appsdestinationslist)
- [`apps:destinations:update`](#appsdestinationsupdate)
- [`apps:devices:delete`](#appsdevicesdelete)
- [`apps:devices:forcechannel`](#appsdevicesforcechannel)
- [`apps:devices:probe`](#appsdevicesprobe)
- [`apps:devices:unforcechannel`](#appsdevicesunforcechannel)
- [`apps:environments:create`](#appsenvironmentscreate)
- [`apps:environments:delete`](#appsenvironmentsdelete)
- [`apps:environments:get`](#appsenvironmentsget)
- [`apps:environments:list`](#appsenvironmentslist)
- [`apps:environments:set`](#appsenvironmentsset)
- [`apps:environments:unset`](#appsenvironmentsunset)
- [`apps:liveupdates:bundle`](#appsliveupdatesbundle)
- [`apps:liveupdates:create`](#appsliveupdatescreate)
- [`apps:liveupdates:generatemanifest`](#appsliveupdatesgeneratemanifest)
- [`apps:liveupdates:generatesigningkey`](#appsliveupdatesgeneratesigningkey)
- [`apps:liveupdates:rollback`](#appsliveupdatesrollback)
- [`apps:liveupdates:rollout`](#appsliveupdatesrollout)
- [`apps:liveupdates:upload`](#appsliveupdatesupload)
- [`apps:liveupdates:register`](#appsliveupdatesregister)
- [`apps:liveupdates:setnativeversions`](#appsliveupdatessetnativeversions)
- [`doctor`](#doctor)
- [`login`](#login)
- [`logout`](#logout)
- [`whoami`](#whoami)
- [`organizations:create`](#organizationscreate)
- [`organizations:get`](#organizationsget)
- [`organizations:list`](#organizationslist)

### `apps:create`

Create a new app in Capawesome Cloud.

```
npx @capawesome/cli apps:create [options]
```

**Options:**

- `--json`: Output in JSON format.
- `--link`: Connect the created app to the local git repository.
- `--name`: The name of the app.
- `--organization-id`: The ID of the organization to create the app in.
- `--type`: The type of the app. Must be `android`, `capacitor`, `cordova`, or `ios`. Defaults to `capacitor`.
- `--yes, -y`: Skip all confirmation prompts.

### `apps:delete`

Delete an app from Capawesome Cloud.

```
npx @capawesome/cli apps:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--yes, -y`: Skip confirmation prompt.

### `apps:get`

Get an existing app from Capawesome Cloud.

```
npx @capawesome/cli apps:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.

### `apps:import`

Import apps from an Ionic Appflow export into Capawesome Cloud. See [Migrating from Ionic Appflow](https://capawesome.io/docs/cloud/migrations/ionic-appflow/index.md).

```
npx @capawesome/cli apps:import [options]
```

**Options:**

- `--dry-run`: Preview the import without creating any resources.
- `--file`: The path to the export file (`.zip`).
- `--include`: Filter which apps to import by name or ID. Can be specified multiple times or comma-separated. Defaults to all apps.
- `--ionic-app-type`: The actual app type of apps exported with the ambiguous app type `ionic`. Must be `capacitor` or `cordova`. Prompted for each app if not provided.
- `--json`: Output in JSON format.
- `--organization-id`: The ID of the organization to import the apps into.

### `apps:list`

List all apps in an organization.

```
npx @capawesome/cli apps:list [options]
```

**Options:**

- `--json`: Output in JSON format.
- `--limit`: The maximum number of apps to return.
- `--offset`: The offset to start returning apps from.
- `--organization-id`: The ID of the organization.

### `apps:transfer`

Transfer an app to another organization.

```
npx @capawesome/cli apps:transfer [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--organization-id`: The ID of the target organization.
- `--yes, -y`: Skip confirmation prompt.

### `apps:link`

Connect a git repository to an app using a [Git connection](https://capawesome.io/docs/cloud/integrations/index.md). The repository is automatically detected from the local git remote (`origin`) and matched against the Git connections of your organization. If no unique match is found, the CLI prompts you to select a Git connection and repository interactively. Git connections can be created on your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page in the Capawesome Cloud Console.

```
npx @capawesome/cli apps:link [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--git-connection`: The name of the Git connection to use. Alternative to `--git-connection-id`.
- `--git-connection-id`: The ID of the Git connection to use. Alternative to `--git-connection`.
- `--path`: The path of the repository (e.g. `owner/repo`) or the clone URL for Git (HTTP/S) connections. Defaults to the path detected from the local git remote (`origin`).

In non-interactive environments (e.g. CI/CD), the `--app-id` option and either the `--git-connection` or `--git-connection-id` option must be provided.

Git connections marked as **restricted** or **legacy** in the Capawesome Cloud Console are backed by a personal credential and cannot be assigned to apps. They are never offered by this command and are rejected when provided via the `--git-connection` or `--git-connection-id` option.

### `apps:unlink`

Disconnect a git repository from an app.

```
npx @capawesome/cli apps:unlink [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--yes, -y`: Skip confirmation prompt.

### `apps:update`

Update an existing app in Capawesome Cloud.

```
npx @capawesome/cli apps:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel`: The name of the default Live Update channel. Pass an empty string to clear it.
- `--channel-discovery`: Enable or disable channel discovery — `true` or `false`.
- `--configuration`: The name of the default native configuration. Pass an empty string to clear it.
- `--environment`: The name of the default environment. Pass an empty string to clear it.
- `--json`: Output in JSON format.
- `--name`: The name of the app.
- `--next-build-number`: The next build number. Must be greater than the latest build number.
- `--stack`: The default build stack for builds without an explicit build stack — `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`. Pass an empty string to use the Capawesome Cloud default.
- `--type`: The type of the app. Must be `android`, `capacitor`, `cordova`, or `ios`.

### `apps:automations:create`

Create a new automation for an app in Capawesome Cloud. See [Getting Started with Automations](https://capawesome.io/docs/cloud/automations/setup/index.md).

```
npx @capawesome/cli apps:automations:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--certificate`: The name of the signing certificate to use for the build.
- `--channel`: The name of a Live Update channel to deploy to (Web only). Can be specified multiple times or comma-separated.
- `--commit-message-pattern`: Only trigger for commits whose message matches this pattern (branch triggers only).
- `--configuration`: The name of the native configuration (Android/iOS only).
- `--destination`: The name of the store destination to deploy to (Android/iOS only).
- `--environment`: The name of the environment to use for the build.
- `--json`: Output in JSON format. Includes the automation ID.
- `--name`: The name of the automation.
- `--platform`: The platform for the build — `android`, `ios`, or `web`.
- `--stack`: The build stack to use for the build process — `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`. If omitted, the automation uses the app's default build stack, or `macos-golden-gate` if the app has none.
- `--trigger-pattern`: Only trigger for branches or tags matching this pattern. Prefix with `!` to exclude. Can be specified multiple times. Defaults to all.
- `--trigger-type`: What triggers the automation — `branch` or `tag`.
- `--type`: The type of build to create — `app-store`, `ad-hoc`, `debug`, `development`, `release`, or `simulator`.

### `apps:automations:delete`

Delete an automation from an app in Capawesome Cloud. This also removes the webhook the automation registered on your repository.

```
npx @capawesome/cli apps:automations:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--automation-id`: The ID of the automation. Either the ID or the name must be provided.
- `--name`: The name of the automation. Either the ID or the name must be provided.
- `--yes, -y`: Skip confirmation prompt.

### `apps:automations:get`

Get an automation from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:automations:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--automation-id`: The ID of the automation. Either the ID or the name must be provided.
- `--json`: Output in JSON format.
- `--name`: The name of the automation. Either the ID or the name must be provided.

### `apps:automations:list`

List all automations for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:automations:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of automations to return.
- `--offset`: The offset to start returning automations from.
- `--platform`: Only list automations for this platform — `android`, `ios`, or `web`.

### `apps:automations:update`

Update an existing automation from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:automations:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--automation-id`: The ID of the automation.
- `--certificate`: The name of the signing certificate to use for the build. Pass an empty string to clear it.
- `--channel`: The name of a Live Update channel to deploy to (Web only). Can be specified multiple times or comma-separated. Pass an empty string to clear them.
- `--commit-message-pattern`: Only trigger for commits whose message matches this pattern (branch triggers only). Pass an empty string to clear it.
- `--configuration`: The name of the native configuration (Android/iOS only). Pass an empty string to clear it.
- `--destination`: The name of the store destination to deploy to (Android/iOS only). Pass an empty string to clear it.
- `--environment`: The name of the environment to use for the build. Pass an empty string to clear it.
- `--json`: Output in JSON format.
- `--name`: The name of the automation.
- `--platform`: The platform for the build — `android`, `ios`, or `web`.
- `--stack`: The build stack to use for the build process — `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`. Pass an empty string to use the app's default build stack, or `macos-golden-gate` if the app has none.
- `--trigger-pattern`: Only trigger for branches or tags matching this pattern. Prefix with `!` to exclude. Can be specified multiple times. Pass an empty string to clear them.
- `--trigger-type`: What triggers the automation — `branch` or `tag`.
- `--type`: The type of build to create — `app-store`, `ad-hoc`, `debug`, `development`, `release`, or `simulator`.

### `apps:builds:cancel`

Cancel an app build.

```
npx @capawesome/cli apps:builds:cancel [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to cancel.

### `apps:builds:create`

Create a new app build.

```
npx @capawesome/cli apps:builds:create [options]
```

**Options:**

- `--aab`: Download the generated AAB file (Android only). Optionally provide a file path.
- `--apk`: Download the generated APK file (Android only). Optionally provide a file path.
- `--app`: Download the generated APP file, a zipped `.app` bundle (iOS simulator builds only). Optionally provide a file path.
- `--app-id`: The ID of the app to create the build for.
- `--certificate`: The name of the certificate to use for the build.
- `--channel`: The name of a channel to deploy to (Web only). Can be specified multiple times or comma-separated.
- `--configuration`: The name of the [native configuration](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md) to apply to the native project (Android/iOS only). Defaults to the app's default native configuration.
- `--destination`: The name of the destination to deploy to (Android/iOS only).
- `--detached`: Exit immediately after creating the build without waiting for completion.
- `--environment`: The name of the environment to use for the build.
- `--failure-summary`: Request an AI-powered failure summary (Capawesome Cloud Assist) if the build fails. Cannot be used together with `--detached`.
- `--form-factor`: The [form factor](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md) of the Android artifact to download. Supported values are `mobile`, `watch`, `tv`, and `automotive`. Without it, the first artifact in the order `mobile`, `watch`, `tv`, `automotive` is downloaded. Only affects `--apk` and `--aab`; the build always includes every application module.
- `--git-ref`: The Git reference (branch, tag, or commit SHA) to build.
- `--ipa`: Download the generated IPA file (iOS only). Optionally provide a file path.
- `--json`: Output in JSON format. This will include additional information such as the build ID.
- `--path`: Path to local source files to upload. Cannot be used together with `--git-ref`.
- `--platform`: The platform for the build. Supported values are `android`, `ios`, and `web`.
- `--release-notes`: [Release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) for the deployment (default text). Requires `--destination`.
- `--release-notes-file`: Path to a JSON file with release notes by locale, e.g. `{"default": "…", "de-DE": "…"}`. Requires `--destination`. Cannot be used together with `--release-notes` or `--release-notes-locale`.
- `--release-notes-locale`: Translated release notes as `<locale>=<text>`, e.g. `de-DE=Fehlerbehebungen`. Can be specified multiple times. Requires `--destination` and `--release-notes`.
- `--share`: Share the build via a public link once it succeeds. Cannot be used together with `--detached`. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md).
- `--share-description`: A description shown to testers on the share page (e.g. what to test). Requires `--share`.
- `--share-expires-in-days`: Number of days after which the share link expires. Requires `--share`.
- `--stack`: The name of the stack to use for the build. Must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`. Defaults to the app's default build stack, or `macos-golden-gate` if the app has none.
- `--type`: The type of build. For Android, supported values are `debug` and `release`. For iOS, supported values are `simulator`, `development`, `ad-hoc`, `app-store`, and `enterprise`. For Web, no type is required.
- `--url`: URL to a zip file to use as build source. Cannot be used together with `--git-ref` or `--path`.
- `--variable`: Ad hoc environment variable in `key=value` format. Can be specified multiple times.
- `--variable-file`: Path to a file containing ad hoc environment variables in `.env` format.
- `--yes, -y`: Skip confirmation prompts.
- `--zip`: Download the generated zip file (Web only). Optionally provide a file path.

### `apps:builds:download`

Download the build artifacts for an app build.

```
npx @capawesome/cli apps:builds:download [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to download artifacts for.
- `--form-factor`: The [form factor](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md) of the Android artifact to download. Supported values are `mobile`, `watch`, `tv`, and `automotive`. Without it, the first artifact in the order `mobile`, `watch`, `tv`, `automotive` is downloaded.
- `--aab`: Download the generated AAB file (Android only). Optionally provide a file path.
- `--apk`: Download the generated APK file (Android only). Optionally provide a file path.
- `--app`: Download the generated APP file, a zipped `.app` bundle (iOS simulator builds only). Optionally provide a file path.
- `--ipa`: Download the generated IPA file (iOS only). Optionally provide a file path.
- `--zip`: Download the generated zip file (Web only). Optionally provide a file path.

### `apps:builds:failure-summary`

Explain why an app build failed using Capawesome Cloud Assist (AI).

```
npx @capawesome/cli apps:builds:failure-summary [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to summarize. Alternative to `--build-number`.
- `--build-number`: The build number to summarize (e.g., "1", "42"). Alternative to `--build-id`.

### `apps:builds:get`

Get an existing app build. When `--json` is set, the response also includes the related job (status, logs, timing) so failed builds can be debugged programmatically.

```
npx @capawesome/cli apps:builds:get [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build.
- `--json`: Output in JSON format. Includes the related job.

### `apps:builds:list`

List all builds for an app. When `--json` is set, each build also includes the related job (status, logs, timing) so failed builds can be debugged programmatically.

```
npx @capawesome/cli apps:builds:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format. Includes the related job for each build.
- `--limit`: The maximum number of builds to return.
- `--number-as-string`: Filter by build number.
- `--offset`: The offset to start returning builds from.
- `--platform`: Filter by platform. Supported values are `android`, `ios`, and `web`.

### `apps:builds:logs`

Display the logs for an ongoing or completed app build.

```
npx @capawesome/cli apps:builds:logs [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to display logs for.

### `apps:builds:run`

Run a succeeded build on a local Android emulator or iOS simulator. The build artifact is downloaded, the target device is started, and the app is installed and launched. See [Run on an emulator or simulator](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md).

```
npx @capawesome/cli apps:builds:run [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to run.
- `--build-number`: The number of the build to run (e.g. `42`). Alternative to `--build-id`.
- `--target`: The ID of the target device to run the build on (AVD ID on Android, UDID on iOS).
- `--target-name`: The name of the target device to run the build on (e.g. `Pixel 8 Pro`, `iPhone 17 Pro`).
- `--target-name-sdk-version`: The SDK version of the target device to run the build on when using `--target-name` (e.g. `26.5` for iOS 26.5 or `35` for Android API 35).

### `apps:builds:share`

Share a succeeded build via a public link. If the build is already shared, the existing share is returned. Only succeeded builds can be shared. Use [`apps:builds:unshare`](#appsbuildsunshare) to revoke a share. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md).

```
npx @capawesome/cli apps:builds:share [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to share.
- `--build-number`: The number of the build to share (e.g. `42`). Alternative to `--build-id`.
- `--description`: A description shown to testers on the share page (e.g. what to test).
- `--expires-in-days`: Number of days after which the share link expires.
- `--json`: Output in JSON format. Includes the share `id`, `qrCodeUrl`, `webUrl`, and `expiresAt`. The `qrCodeUrl` is a PNG image of a QR code pointing to the share page.

### `apps:builds:unshare`

Revoke the public share link of a build. The link is invalidated immediately and the share page stops working. See [Revoke a share](https://capawesome.io/docs/cloud/native-builds/share-a-build/#revoke-a-share).

```
npx @capawesome/cli apps:builds:unshare [options]
```

**Options:**

- `--app-id`: The ID of the app the build belongs to.
- `--build-id`: The ID of the build to unshare.
- `--build-number`: The number of the build to unshare (e.g. `42`). Alternative to `--build-id`.
- `--yes`: Skip the confirmation prompt.

### `apps:certificates:create`

Create a new certificate for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:certificates:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--file`: Path to the certificate file.
- `--json`: Output in JSON format.
- `--key-alias`: Key alias for the certificate.
- `--key-password`: Key password for the certificate.
- `--name`: The name of the certificate.
- `--password`: Password for the certificate.
- `--platform`: The platform of the certificate. Supported values are `android`, `ios`, and `web`.
- `--provisioning-profile`: Paths to provisioning profile files to upload and link. Can be specified multiple times.
- `--type`: Deprecated. The certificate type is now detected automatically.
- `--yes, -y`: Skip optional prompts.

### `apps:certificates:delete`

Delete a certificate from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:certificates:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--certificate-id`: The ID of the certificate.
- `--name`: The name of the certificate.
- `--platform`: The platform of the certificate (`android`, `ios`, `web`).
- `--type`: The type of the certificate. Supported values are `development` and `production`.
- `--yes, -y`: Skip confirmation prompt.

### `apps:certificates:get`

Get a certificate from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:certificates:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--certificate-id`: The ID of the certificate.
- `--json`: Output in JSON format.
- `--name`: The name of the certificate.
- `--platform`: The platform of the certificate (`android`, `ios`, `web`).
- `--type`: The type of the certificate. Supported values are `development` and `production`.

### `apps:certificates:list`

List all certificates for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:certificates:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of certificates to return.
- `--offset`: The offset to start returning certificates from.
- `--platform`: Filter by platform. Supported values are `android`, `ios`, and `web`.
- `--type`: Filter by type. Supported values are `development` and `production`.

### `apps:certificates:update`

Update an existing certificate from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:certificates:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--certificate-id`: The ID of the certificate.
- `--key-alias`: Key alias for the certificate.
- `--key-password`: Key password for the certificate.
- `--name`: The name of the certificate.
- `--password`: Password for the certificate.
- `--type`: Deprecated. The certificate type is now detected automatically.

### `apps:channels:create`

Create a new channel for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:channels:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--ignore-errors`: Ignore errors when creating the channel. This is useful for CI/CD pipelines where the channel may already exist. Defaults to `false`.
- `--json`: Output in JSON format.
- `--name`: The name of the channel.
- `--protected`: Whether to protect the channel or not. Defaults to `false`.

### `apps:channels:delete`

Delete a channel from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:channels:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel-id`: The ID of the channel. Either the ID or the name of the channel must be provided.
- `--name`: The name of the channel. Either the ID or the name of the channel must be provided.
- `--yes, -y`: Skip confirmation prompt.

### `apps:channels:get`

Get a channel from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:channels:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel-id`: The ID of the channel. Either the ID or the name of the channel must be provided.
- `--json`: Output in JSON format.
- `--name`: The name of the channel. Either the ID or the name of the channel must be provided.

### `apps:channels:list`

List all channels for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:channels:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of channels to return.
- `--offset`: The offset to start returning channels from.

### `apps:channels:pause`

Pause an app channel.

```
npx @capawesome/cli apps:channels:pause [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel`: The name of the channel to pause.

### `apps:channels:resume`

Resume an app channel.

```
npx @capawesome/cli apps:channels:resume [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel`: The name of the channel to resume.

### `apps:channels:update`

Update an existing channel from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:channels:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel-id`: The ID of the channel.
- `--name`: The name of the channel.
- `--protected`: Whether to protect the channel or not.

### `apps:configurations:create`

Create a new native configuration for an app in Capawesome Cloud. See [Set Up Native Configurations](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md).

```
npx @capawesome/cli apps:configurations:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--display-name`: The app name that is displayed on the home screen.
- `--json`: Output in JSON format. Includes the native configuration ID.
- `--name`: The name of the native configuration.
- `--package-name`: The package name of the app — the application ID on Android, the bundle ID on iOS.

### `apps:configurations:delete`

Delete a native configuration from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:configurations:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--configuration-id`: The ID of the native configuration. Either the ID or the name must be provided.
- `--name`: The name of the native configuration. Either the ID or the name must be provided.
- `--yes, -y`: Skip confirmation prompt.

### `apps:configurations:get`

Get a native configuration from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:configurations:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--configuration-id`: The ID of the native configuration. Either the ID or the name must be provided.
- `--json`: Output in JSON format.
- `--name`: The name of the native configuration. Either the ID or the name must be provided.

### `apps:configurations:list`

List all native configurations for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:configurations:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of native configurations to return.
- `--offset`: The offset to start returning native configurations from.

### `apps:configurations:update`

Update an existing native configuration from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:configurations:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--configuration-id`: The ID of the native configuration.
- `--display-name`: The app name that is displayed on the home screen. Pass an empty string to clear it.
- `--json`: Output in JSON format.
- `--name`: The name of the native configuration.
- `--package-name`: The package name of the app — the application ID on Android, the bundle ID on iOS. Pass an empty string to clear it.

### `apps:deployments:cancel`

Cancel an ongoing app deployment.

```
npx @capawesome/cli apps:deployments:cancel [options]
```

**Options:**

- `--app-id`: The ID of the app the deployment belongs to.
- `--deployment-id`: The ID of the deployment to cancel.

### `apps:deployments:create`

Create a new app deployment.

```
npx @capawesome/cli apps:deployments:create [options]
```

**Options:**

- `--app-id`: The ID of the app to create the deployment for.
- `--build-id`: The ID of the build to deploy. Alternative to `--build-number`.
- `--build-number`: The build number to deploy (e.g., "1", "42"). Alternative to `--build-id`.
- `--channel`: The name of the channel to deploy the build to (Web only).
- `--destination`: The name of the destination to deploy to (Android/iOS only).
- `--detached`: Exit immediately after creating the deployment without waiting for completion.
- `--failure-summary`: Request an AI-powered failure summary (Capawesome Cloud Assist) if the deployment fails.
- `--json`: Output in JSON format.
- `--release-notes`: [Release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) for the deployment (default text). Android/iOS only.
- `--release-notes-file`: Path to a JSON file with release notes by locale, e.g. `{"default": "…", "de-DE": "…"}`. Cannot be used together with `--release-notes` or `--release-notes-locale`.
- `--release-notes-locale`: Translated release notes as `<locale>=<text>`, e.g. `de-DE=Fehlerbehebungen`. Can be specified multiple times. Requires `--release-notes`.

### `apps:deployments:failure-summary`

Explain why an app deployment failed using Capawesome Cloud Assist (AI).

```
npx @capawesome/cli apps:deployments:failure-summary [options]
```

**Options:**

- `--app-id`: The ID of the app the deployment belongs to.
- `--deployment-id`: The ID of the deployment to summarize.

### `apps:deployments:get`

Get an existing app deployment. When `--json` is set, the response also includes the related job (status, logs, timing) so failed deployments can be debugged programmatically.

```
npx @capawesome/cli apps:deployments:get [options]
```

**Options:**

- `--app-id`: The ID of the app the deployment belongs to.
- `--deployment-id`: The ID of the deployment.
- `--json`: Output in JSON format. Includes the related job.

### `apps:deployments:list`

List all deployments for an app. When `--json` is set, each deployment also includes the related job (status, logs, timing) so failed deployments can be debugged programmatically.

```
npx @capawesome/cli apps:deployments:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--build-id`: Filter by build ID.
- `--channel-id`: Filter by channel ID.
- `--destination-id`: Filter by destination ID.
- `--json`: Output in JSON format. Includes the related job for each deployment.
- `--limit`: The maximum number of deployments to return.
- `--offset`: The offset to start returning deployments from.

### `apps:deployments:logs`

Display the logs for an ongoing or completed app deployment.

```
npx @capawesome/cli apps:deployments:logs [options]
```

**Options:**

- `--app-id`: The ID of the app the deployment belongs to.
- `--deployment-id`: The ID of the deployment to display logs for.

### `apps:destinations:create`

Create a new destination for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:destinations:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--name`: The name of the destination.
- `--platform`: The platform of the destination. Supported values are `android` and `ios`.
- `--type`: The type of the destination. Supported values are `firebase-app-distribution`, `google-play`, and `huawei-appgallery` for Android, and `apple-app-store-connect` and `firebase-app-distribution` for iOS. Defaults to `google-play` for Android and `apple-app-store-connect` for iOS in non-interactive environments.
- `--android-build-artifact-type`: Android build artifact type. Supported values are `aab` and `apk`.
- `--android-package-name`: Android package name.
- `--android-release-status`: Android release status. Supported values are `completed` and `draft`.
- `--google-play-track`: Google Play track.
- `--google-service-account-key-file`: Path to the Google service account key JSON file.
- `--apple-api-key-file`: Path to the Apple API key (.p8) file.
- `--apple-app-id`: Apple App ID.
- `--apple-app-password`: Apple app-specific password.
- `--apple-beta-group`: Name of an external TestFlight beta group to distribute to. Can be specified multiple times or comma-separated. Requires an API key.
- `--apple-id`: Apple ID.
- `--apple-issuer-id`: Apple Issuer ID.
- `--apple-reject-if-possible`: Cancel a submission waiting for review before submitting the new build. Pass `false` to turn it off.
- `--apple-release-type`: Release type of the App Store version after approval. Supported values are `manual` and `after-approval`.
- `--apple-submit-for-review`: Submit the build for App Review after the upload. Pass `false` to turn it off. Requires an API key.
- `--apple-team-id`: Apple Team ID.
- `--default-language`: Language of the default release notes text, e.g. `en-US` (Google Play and Huawei AppGallery only).
- `--firebase-app-id`: Firebase app ID.
- `--firebase-tester-group`: Firebase tester group alias. Can be specified multiple times or comma-separated.
- `--huawei-app-id`: Huawei AppGallery app ID.
- `--huawei-client-id`: Huawei AppGallery Connect API client ID.
- `--huawei-client-secret`: Huawei AppGallery Connect API client secret.

### `apps:destinations:delete`

Delete a destination from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:destinations:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--destination-id`: The ID of the destination.
- `--name`: The name of the destination.
- `--platform`: The platform of the destination (`android`, `ios`).
- `--yes, -y`: Skip confirmation prompt.

### `apps:destinations:get`

Get a destination from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:destinations:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--destination-id`: The ID of the destination.
- `--json`: Output in JSON format.
- `--name`: The name of the destination.
- `--platform`: The platform of the destination (`android`, `ios`).

### `apps:destinations:list`

List all destinations for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:destinations:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of destinations to return.
- `--offset`: The offset to start returning destinations from.
- `--platform`: Filter by platform. Supported values are `android` and `ios`.

### `apps:destinations:update`

Update an existing destination from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:destinations:update [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--destination-id`: The ID of the destination.
- `--name`: The name of the destination.
- `--android-build-artifact-type`: Android build artifact type. Supported values are `aab` and `apk`.
- `--android-package-name`: Android package name.
- `--android-release-status`: Android release status. Supported values are `completed` and `draft`.
- `--app-google-service-account-key-id`: App Google Service Account Key ID.
- `--google-play-track`: Google Play track.
- `--apple-api-key-id`: Apple API Key ID.
- `--apple-app-id`: Apple App ID.
- `--apple-app-password`: Apple app-specific password.
- `--apple-beta-group`: Name of an external TestFlight beta group to distribute to. Can be specified multiple times or comma-separated. Pass `--apple-beta-group=` to remove all groups. Requires an API key.
- `--apple-id`: Apple ID.
- `--apple-issuer-id`: Apple Issuer ID.
- `--apple-reject-if-possible`: Cancel a submission waiting for review before submitting the new build. Pass `false` to turn it off.
- `--apple-release-type`: Release type of the App Store version after approval. Supported values are `manual` and `after-approval`.
- `--apple-submit-for-review`: Submit the build for App Review after the upload. Pass `false` to turn it off. Requires an API key.
- `--apple-team-id`: Apple Team ID.
- `--app-apple-api-key-id`: App Apple API Key ID.
- `--default-language`: Language of the default release notes text, e.g. `en-US` (Google Play and Huawei AppGallery only). Pass `--default-language=` to clear it.
- `--firebase-app-id`: Firebase app ID.
- `--firebase-tester-group`: Firebase tester group alias. Can be specified multiple times or comma-separated. Pass `--firebase-tester-group=` to remove all groups.
- `--huawei-app-id`: Huawei AppGallery app ID.
- `--huawei-client-id`: Huawei AppGallery Connect API client ID.
- `--huawei-client-secret`: Huawei AppGallery Connect API client secret.

### `apps:devices:delete`

Delete a device from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:devices:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--device-id`: The ID of the device.
- `--yes, -y`: Skip confirmation prompt.

### `apps:devices:forcechannel`

Force a device to use a specific channel.

```
npx @capawesome/cli apps:devices:forcechannel [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--device-id`: The ID of the device. Can be specified multiple times.
- `--channel`: The name of the channel to force.

### `apps:devices:probe`

Check whether a device would receive a live update. This is useful for debugging and testing purposes, especially when setting up new devices or troubleshooting existing ones.

```
npx @capawesome/cli apps:devices:probe [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--device-id`: The ID of the device.
- `--json`: Output in JSON format.

### `apps:devices:unforcechannel`

Remove the forced channel from a device.

```
npx @capawesome/cli apps:devices:unforcechannel [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--device-id`: The ID of the device. Can be specified multiple times.

### `apps:environments:create`

Create a new environment for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:create [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--name`: The name of the environment.

### `apps:environments:delete`

Delete an environment from an app in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:delete [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--environment-id`: The ID of the environment. Either the ID or name must be provided.
- `--name`: The name of the environment. Either the ID or name must be provided.
- `--yes, -y`: Skip confirmation prompt.

### `apps:environments:get`

Get an existing environment for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:get [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--environment-id`: The ID of the environment. Either the ID or name must be provided.
- `--name`: The name of the environment. Either the ID or name must be provided.
- `--json`: Output in JSON format.

### `apps:environments:list`

List all environments for an app in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:list [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--json`: Output in JSON format.
- `--limit`: The maximum number of environments to return.
- `--offset`: The offset to start returning environments from.

### `apps:environments:set`

Set environment variables and secrets for an environment in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:set [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--environment-id`: The ID of the environment. Either the ID or name must be provided.
- `--name`: The name of the environment. Either the ID or name must be provided.
- `--variable`: Environment variable in `key=value` format. Can be specified multiple times.
- `--variable-file`: Path to a file containing environment variables in `.env` format.
- `--secret`: Environment secret in `key=value` format. Can be specified multiple times.
- `--secret-file`: Path to a file containing environment secrets in `.env` format.

### `apps:environments:unset`

Unset environment variables and secrets for an environment in Capawesome Cloud.

```
npx @capawesome/cli apps:environments:unset [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--environment-id`: The ID of the environment. Either the ID or name must be provided.
- `--name`: The name of the environment. Either the ID or name must be provided.
- `--variable`: Key of the environment variable to unset. Can be specified multiple times.
- `--secret`: Key of the environment secret to unset. Can be specified multiple times.

### `apps:liveupdates:bundle`

Generate manifest file and compress web assets into a zip file.

```
npx @capawesome/cli apps:liveupdates:bundle [options]
```

**Options:**

- `--input-path`: Path to the web assets directory.
- `--output-path`: Output path for the generated artifact file. Defaults to `./bundle.zip`.
- `--overwrite`: Overwrite output file if it already exists. Defaults to `false`.
- `--skip-manifest`: Skip manifest file generation. Defaults to `false`.

### `apps:liveupdates:create`

Create a new live update by building and deploying web assets using Capawesome Cloud Runners.

```
npx @capawesome/cli apps:liveupdates:create [options]
```

**Options:**

- `--android-eq`: The exact Android versionCode for the live update.
- `--android-max`: The maximum Android versionCode for the live update.
- `--android-min`: The minimum Android versionCode for the live update.
- `--app-id`: The ID of the app to create the live update for.
- `--certificate`: The name of the certificate to use for the build.
- `--channel`: The name of the channel to deploy to. Can be specified multiple times.
- `--custom-property`: A custom property to assign to the build. Must be in the format `key=value`. Can be specified multiple times.
- `--environment`: The name of the environment to use for the build.
- `--git-ref`: The Git reference (branch, tag, or commit SHA) to build.
- `--ios-eq`: The exact iOS CFBundleVersion for the live update.
- `--ios-max`: The maximum iOS CFBundleVersion for the live update.
- `--ios-min`: The minimum iOS CFBundleVersion for the live update.
- `--json`: Output in JSON format.
- `--path`: Path to local source files to upload. Cannot be used together with `--git-ref` or `--url`.
- `--rollout-percentage`: The rollout percentage for the deployment (0-100). Defaults to `100`.
- `--stack`: The build stack to use for the build process. Must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`. Defaults to the app's default build stack, or `macos-golden-gate` if the app has none.
- `--url`: URL to a zip file to use as build source. Cannot be used together with `--git-ref` or `--path`.
- `--variable`: Ad hoc environment variable in `key=value` format. Can be specified multiple times.
- `--variable-file`: Path to a file containing ad hoc environment variables in `.env` format.
- `--yes, -y`: Skip confirmation prompts.

### `apps:liveupdates:generatemanifest`

Generate a manifest file.

```
npx @capawesome/cli apps:liveupdates:generatemanifest [options]
```

**Options:**

- `--path`: Path to the web assets folder (e.g. `www` or `dist`).

### `apps:liveupdates:generatesigningkey`

Generate a new code signing key pair for Live Updates. This command creates an RSA key pair that can be used to sign and verify Live Updates bundles.

```
npx @capawesome/cli apps:liveupdates:generatesigningkey [options]
```

**Options:**

- `--app-type`: The app type to configure code signing for. Either `capacitor` or `cordova`.
- `--key-size`: The RSA key size in bits. Must be `2048`, `3072`, or `4096`. Defaults to `2048`.
- `--public-key-path`: Path where the public key should be saved. Defaults to `public.pem`.
- `--private-key-path`: Path where the private key should be saved. Defaults to `private.pem`.

### `apps:liveupdates:rollback`

Rollback the active build in a channel to a previous deployment.

```
npx @capawesome/cli apps:liveupdates:rollback [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel`: The name of the channel to rollback.
- `--steps`: The number of deployments to go back (1-5).

### `apps:liveupdates:rollout`

Update the rollout percentage of the active build in a channel.

```
npx @capawesome/cli apps:liveupdates:rollout [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--channel`: The name of the channel to update rollout for.
- `--percentage`: The rollout percentage (0-100).

### `apps:liveupdates:upload`

Upload a locally built bundle and deploy it to a channel.

```
npx @capawesome/cli apps:liveupdates:upload [options]
```

**Options:**

- `--android-eq`: The exact Android version code (`versionCode`) that the bundle does not support.
- `--android-max`: The maximum Android version code (`versionCode`) that the bundle supports.
- `--android-min`: The minimum Android version code (`versionCode`) that the bundle supports.
- `--app-id`: The ID of the app.
- `--artifact-type`: The type of artifact to upload. Must be `zip` or `manifest`. Defaults to `zip`.
- `--channel`: The channel to deploy the bundle to.
- `--commit-message`: The commit message of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--commit-ref`: The commit ref of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--commit-sha`: The commit SHA of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--custom-property`: A custom property to assign to the bundle. Must be in the format `key=value`. Can be specified multiple times.
- `--electron-eq`: The exact Electron app version (`version` in `electron/package.json`) that the bundle does not support. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--electron-max`: The maximum Electron app version (`version` in `electron/package.json`) that the bundle supports. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--electron-min`: The minimum Electron app version (`version` in `electron/package.json`) that the bundle supports. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--git-ref`: The Git reference (branch, tag, or commit SHA) to associate with the bundle.
- `--ios-eq`: The exact iOS version code (`CFBundleVersion`) that the bundle does not support.
- `--ios-max`: The maximum iOS version code (`CFBundleVersion`) that the bundle supports.
- `--ios-min`: The minimum iOS version code (`CFBundleVersion`) that the bundle supports.
- `--json`: Output in JSON format.
- `--path`: The path to the bundle to upload. Must be a folder or zip archive.
- `--private-key`: The private key to sign the bundle with. Can be a file path to a .pem file or the private key content as plain text.
- `--rollout-percentage`: The percentage of devices to deploy the bundle to. Must be an integer between 0 and 100.
- `--yes, -y`: Skip confirmation prompts.

### `apps:liveupdates:register`

Register a self-hosted bundle URL and deploy it to a channel.

```
npx @capawesome/cli apps:liveupdates:register [options]
```

**Options:**

- `--android-eq`: The exact Android version code (`versionCode`) that the bundle does not support.
- `--android-max`: The maximum Android version code (`versionCode`) that the bundle supports.
- `--android-min`: The minimum Android version code (`versionCode`) that the bundle supports.
- `--app-id`: The ID of the app.
- `--channel`: The channel to deploy the bundle to.
- `--commit-message`: The commit message of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--commit-ref`: The commit ref of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--commit-sha`: The commit SHA of the Git commit that the bundle is linked to. Deprecated, use `--git-ref` instead.
- `--custom-property`: A custom property to assign to the bundle. Must be in the format `key=value`. Can be specified multiple times.
- `--electron-eq`: The exact Electron app version (`version` in `electron/package.json`) that the bundle does not support. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--electron-max`: The maximum Electron app version (`version` in `electron/package.json`) that the bundle supports. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--electron-min`: The minimum Electron app version (`version` in `electron/package.json`) that the bundle supports. Must be in the format `major[.minor[.patch]]`; prerelease suffixes are not supported.
- `--git-ref`: The Git reference (branch, tag, or commit SHA) to associate with the bundle.
- `--ios-eq`: The exact iOS version code (`CFBundleVersion`) that the bundle does not support.
- `--ios-max`: The maximum iOS version code (`CFBundleVersion`) that the bundle supports.
- `--ios-min`: The minimum iOS version code (`CFBundleVersion`) that the bundle supports.
- `--json`: Output in JSON format.
- `--path`: Path to zip file for code signing only.
- `--private-key`: The private key to sign the bundle with. Can be a file path to a .pem file or the private key content as plain text.
- `--rollout-percentage`: The percentage of devices to deploy the bundle to. Must be an integer between 0 and 100.
- `--url`: The URL to the self-hosted bundle file. The URL must start with `https://`.
- `--yes, -y`: Skip confirmation prompts.

### `apps:liveupdates:setnativeversions`

Set native version constraints on a web build.

```
npx @capawesome/cli apps:liveupdates:setnativeversions [options]
```

**Options:**

- `--app-id`: The ID of the app.
- `--build-id`: The ID of the build to update.
- `--android-eq`: The exact Android version code (`versionCode`) that the build supports.
- `--android-max`: The maximum Android version code (`versionCode`) that the build supports.
- `--android-min`: The minimum Android version code (`versionCode`) that the build supports.
- `--ios-eq`: The exact iOS bundle version (`CFBundleVersion`) that the build supports.
- `--ios-max`: The maximum iOS bundle version (`CFBundleVersion`) that the build supports.
- `--ios-min`: The minimum iOS bundle version (`CFBundleVersion`) that the build supports.

### `doctor`

Print various information about the Capawesome CLI and your environment. This is useful for debugging issues with the CLI or your environment.

```
npx @capawesome/cli doctor
```

### `login`

Log in to Capawesome Cloud.

```
npx @capawesome/cli login
```

**Options:**

- `--token`: The token to use for authentication.

### `logout`

Log out of Capawesome Cloud.

```
npx @capawesome/cli logout
```

### `whoami`

Show the current logged-in user.

```
npx @capawesome/cli whoami
```

### `organizations:create`

Create a new organization in Capawesome Cloud.

```
npx @capawesome/cli organizations:create [options]
```

**Options:**

- `--json`: Output in JSON format.
- `--name`: The name of the organization.

### `organizations:get`

Get an existing organization from Capawesome Cloud.

```
npx @capawesome/cli organizations:get [options]
```

**Options:**

- `--json`: Output in JSON format.
- `--organization-id`: The ID of the organization.

### `organizations:list`

List all organizations the current user belongs to.

```
npx @capawesome/cli organizations:list [options]
```

**Options:**

- `--json`: Output in JSON format.
- `--limit`: The maximum number of organizations to return.
- `--offset`: The offset to start returning organizations from.

# Examples

Practical recipes using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md). Each one is a starting point you can adapt — see the [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md) for the full set of options on any command.

## List your apps and builds

To see what's in your account, list your apps, then the builds for one of them:

```
npx @capawesome/cli apps:list
npx @capawesome/cli apps:builds:list --app-id "$APP_ID"
```

## Build a debug APK for Android

For quick on-device testing, build a debug APK from a Git branch:

```
npx @capawesome/cli apps:builds:create --platform android --type debug --git-ref main
```

## Build an iOS app for the App Store

To produce a store-ready iOS build, use the `app-store` type with the matching signing certificate:

```
npx @capawesome/cli apps:builds:create --platform ios --type app-store --git-ref main
```

## Download a build artifact

Once a build finishes, download its artifact to a local path:

```
npx @capawesome/cli apps:builds:download --apk ./app.apk
npx @capawesome/cli apps:builds:download --apk --form-factor watch
```

`--form-factor` selects which Android artifact to download, for example the Wear OS one — see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

## Build your web app and publish a Live Update

To ship a web change over the air, build locally and upload the result to a channel:

```
npm run build
npx @capawesome/cli apps:liveupdates:upload --channel production
```

## Deploy a Live Update to multiple channels

To ship the same bundle to several channels in one go, repeat the `--channel` flag for each target:

```
npx @capawesome/cli apps:liveupdates:create --channel production --channel staging
```

## Roll back the latest Live Update

If a release misbehaves, roll the channel back to the previous bundle:

```
npx @capawesome/cli apps:liveupdates:rollback --channel production
```

## Sign and publish a bundle

To publish a signed bundle, pass your private key alongside the upload:

```
npx @capawesome/cli apps:liveupdates:upload --channel production --private-key private.pem
```

## Share a build with testers

To give external testers a public link they can open without an account, share a succeeded build:

```
npx @capawesome/cli apps:builds:share --description "Please test the new checkout flow"
```

Add `--json` to get the share `webUrl` and a `qrCodeUrl` you can embed in Slack or a pull request. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md).

## Submit a build to a store

To submit an existing build to a configured destination, create a deployment:

```
npx @capawesome/cli apps:deployments:create --build-number 42 --destination my-destination
```

## Automate in CI

Running these commands from a pipeline has its own considerations — token authentication, non-interactive flags, parsing JSON output, and waiting on builds. See [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) for a complete walkthrough and a full build-and-deploy CI example.

## Next steps

- [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md) — every command and option.
- [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) — automate the CLI in scripts and CI.
- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — global flags, JSON output, and exit codes.
- [Integrations](https://capawesome.io/docs/cloud/integrations/index.md) — wire these recipes into your CI/CD provider.

# Installation

The Capawesome Cloud CLI is distributed as the [`@capawesome/cli`](https://www.npmjs.com/package/@capawesome/cli) npm package and runs on [Node.js](https://nodejs.org). Any current LTS version of Node.js works, and npm comes bundled with it — so there's nothing else to install.

## Run with npx (recommended)

You don't need to install anything — `npx` downloads and runs the CLI on demand:

```
npx @capawesome/cli apps:list
```

This is the recommended approach for occasional use and for CI, because it doesn't rely on a global install being present.

## Install globally

If you reach for the CLI often, install it globally so it doesn't have to be fetched on each run:

```
npm install -g @capawesome/cli
```

You still invoke it the same way — `npx @capawesome/cli …` — but npx now uses the globally installed copy instead of downloading it every time.

## Pin a version for CI

In CI/CD, pin the version so pipelines are reproducible and upgrades happen on purpose rather than silently with each run:

```
npx @capawesome/cli@4.9.3 apps:builds:create
```

## Update

Update a global install to the latest version with:

```
npm install -g @capawesome/cli@latest
```

## Next steps

- [Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md) — log in or set up a token before your first command.
- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — command anatomy, global flags, and JSON output.

# Scripting

The CLI is designed to run unattended. This guide covers what changes when there's no human at the keyboard: authenticating without a browser, running commands non-interactively, parsing JSON output, waiting on long-running jobs, and failing the pipeline when something goes wrong.

If you're looking for ready-made snippets, see [Examples](https://capawesome.io/docs/cloud/cli/examples/index.md). This page explains the underlying behavior so you can adapt them safely.

## Authenticate with a token

Interactive login doesn't work on a build server. Instead, create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) and expose it as the `CAPAWESOME_TOKEN` environment variable — the CLI reads it automatically, so you don't need to pass it on every command:

```
export CAPAWESOME_TOKEN="$YOUR_CI_SECRET"
npx @capawesome/cli whoami
```

Store the token as a secret in your CI provider and never commit it to version control. You can also pass `--token` on an individual command if you prefer; see [Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md) for details.

Alternative variable

`CAPAWESOME_CLOUD_TOKEN` is also accepted and takes precedence over `CAPAWESOME_TOKEN` if both are set.

## Run commands non-interactively

Run a command without a TTY and two things will trip you up: confirmation prompts and missing required values. Pass every required value as a flag, and add `--yes` to skip confirmations:

```
npx @capawesome/cli apps:builds:create \
  --app-id "$APP_ID" \
  --platform android \
  --type release \
  --git-ref main \
  --yes
```

The CLI only prompts when both input and output are a terminal and the `CI` environment variable is unset. In CI it therefore won't hang waiting for input — if a required value like `--app-id` is missing, it exits with a non-zero code instead. Always pass the required flags explicitly.

## Pin the CLI version

`npx @capawesome/cli` resolves to the latest version, which can change behavior between pipeline runs. Pin a version so your automation stays reproducible:

```
npx @capawesome/cli@4.9.3 whoami
```

## Parse JSON output

Add `--json` to get machine-readable output instead of human-readable text. How you consume it depends on the command.

### Commands that print only JSON

Read-style commands — such as `apps:list`, `apps:builds:get`, or `apps:channels:list` — print nothing but the JSON object. You can pipe them straight into [jq](https://jqlang.github.io/jq/):

```
npx @capawesome/cli apps:list --json | jq -r '.[].id'
```

### Commands that stream progress

Commands that do long-running work — `apps:builds:create` and `apps:liveupdates:upload` — print progress lines to standard output while they run and the JSON object only at the very end. Both share the same stream, so piping directly into `jq` fails on the progress lines. Capture the output and extract the trailing JSON block instead:

```
OUTPUT=$(mktemp)
npx @capawesome/cli apps:builds:create \
  --app-id "$APP_ID" \
  --platform android \
  --type release \
  --git-ref main \
  --json \
  --yes | tee "$OUTPUT"
BUILD_ID=$(sed -n '/^{/,$p' "$OUTPUT" | jq -r '.id')
rm "$OUTPUT"
```

The JSON is pretty-printed, so it begins with a `{` on its own line. `sed -n '/^{/,$p'` keeps everything from that line to the end and drops the progress above it, while `tee` still shows the progress in your CI logs.

## Wait for a build to finish

By default, `apps:builds:create` and `apps:deployments:create` wait for the job to complete and exit non-zero if it fails — so a failed build stops your pipeline with no extra work on your part.

Pass `--detached` when you'd rather not block, for example to run other steps while the build runs. There's a trade-off: a detached command exits `0` as soon as the build is *queued*, regardless of whether it later succeeds or fails. To get the real outcome, poll [`apps:builds:get`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsget) — which prints clean JSON — until the status is terminal:

```
while true; do
  STATUS=$(npx @capawesome/cli apps:builds:get \
    --app-id "$APP_ID" \
    --build-id "$BUILD_ID" \
    --json | jq -r '.job.status')
  case "$STATUS" in
    succeeded) echo "Build succeeded"; break ;;
    failed|canceled|rejected|timed_out) echo "Build $STATUS"; exit 1 ;;
    *) sleep 10 ;; # queued, pending, in_progress
  esac
done
```

The build's status lives on the nested `job` object (`.job.status`), not at the top level.

## Handle failures

The CLI exits `0` on success and non-zero on failure, so in most CI systems a failed command stops the job automatically. A build or deployment that fails counts as a failure and exits non-zero — unless you detached from it, in which case you own the polling (see above).

To understand *why* a build failed, request an AI-generated summary with `--failure-summary` (powered by [Capawesome Cloud Assist](https://capawesome.io/docs/cloud/assist/index.md)), or fetch one afterward with [`apps:builds:failure-summary`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsfailure-summary).

Transient network errors

The CLI automatically retries failed requests caused by network errors or `5xx` responses, and honors the `HTTPS_PROXY` and `HTTP_PROXY` environment variables — useful behind a corporate proxy.

## Make repeated runs idempotent

A pipeline shouldn't fail just because a resource already exists. `apps:channels:create` accepts `--ignore-errors`, which exits `0` even when the channel is already there, so you can create-then-use without a separate existence check:

```
npx @capawesome/cli apps:channels:create --app-id "$APP_ID" --name production --ignore-errors
```

This flag is specific to channel creation.

## Full example: build and deploy in CI

Putting it together — authenticate with a token from a CI secret, pin the version, ensure the channel exists, then build and deploy non-interactively. Because the default behavior waits and fails on a bad build, no extra error handling is needed to fail the pipeline:

```
# CAPAWESOME_TOKEN is provided as a CI secret
CLI="npx @capawesome/cli@4.9.3"

# Ensure the channel exists (won't fail if it already does)
$CLI apps:channels:create --app-id "$APP_ID" --name production --ignore-errors

# Build the web app in the cloud and deploy it to the channel
$CLI apps:builds:create \
  --app-id "$APP_ID" \
  --platform web \
  --channel production \
  --git-ref "$GIT_SHA" \
  --yes
```

## Next steps

- [Examples](https://capawesome.io/docs/cloud/cli/examples/index.md) — ready-made recipes for builds, Live Updates, and CI.
- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — command anatomy, global flags, and the `doctor` command.
- [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md) — every command and its options.
- [Integrations](https://capawesome.io/docs/cloud/integrations/index.md) — wire these scripts into your CI/CD provider.

# Telemetry

The Capawesome Cloud CLI sends **crash reports** so we can find and fix bugs you run into. That's the only data it collects — there's no usage analytics and no tracking of which commands you run day to day.

## What's collected

When a command fails with an unexpected error, the CLI sends a crash report. A report includes the error and its stack trace, the CLI version, and context about the command that failed. If you're signed in, it also includes your account's user ID, so we can follow up on issues you run into. Expected errors, such as failed API requests and validation errors, are not reported.

## Opt out

Set the following environment variable to disable crash reporting entirely:

```
export CAPAWESOME_TELEMETRY_DISABLED=1
```

With it set, nothing is ever sent. Add it to your shell profile to make it permanent, or to your CI environment to disable reporting across every pipeline run.

## First-run notice

The first time you run the CLI interactively, it prints a short notice pointing here. It shows only once per machine and never in CI, so it won't clutter your pipeline logs.

## Next steps

- [Usage](https://capawesome.io/docs/cloud/cli/usage/index.md) — global flags and JSON output.
- [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) — running the CLI unattended in CI.

# Usage

This page covers how every CLI command works — the command pattern, the flags that apply everywhere, how to read output, and how to diagnose problems. For automating the CLI in CI, see [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md).

## Running commands

Commands follow the pattern `apps:<resource>:<action>` — for example `apps:builds:create` or `apps:channels:list`. The resource is what you're acting on (builds, channels, deployments, …) and the action is what you're doing to it (create, list, get, …). Browse them all in the [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md).

Most commands prompt for any required values you don't provide, so you can run them interactively and fill in the blanks. Pass those values as flags instead to run non-interactively — which is what you'll do in scripts and CI.

## Global flags

These flags work across commands:

| Flag       | Description                                                                                                      |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `--app-id` | The target app ID (skips the app prompt).                                                                        |
| `--token`  | An API token for non-interactive [authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md). |
| `--yes`    | Skip confirmation prompts (for scripts and CI).                                                                  |
| `--json`   | Output machine-readable JSON instead of human-readable text.                                                     |
| `--help`   | Show help for any command.                                                                                       |

For commands that act on a specific app, pass `--app-id` to skip the interactive app picker — essential in CI, where there's nobody to answer the prompt.

## Getting help

Show the available commands, or help for a specific one:

```
npx @capawesome/cli --help
npx @capawesome/cli apps:builds:create --help
```

`--help` lists every flag a command accepts, so it's the fastest way to discover options without leaving the terminal.

## JSON output

Add `--json` to any command to get structured output you can parse in scripts — for example, to read a new build's ID out of `apps:builds:create --json` and use it in a later step. Note that commands which stream progress print the JSON only at the end, so parsing them needs a little care. See [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) for the details and recipes.

## Exit codes

The CLI exits with status code `0` on success and a non-zero code on failure. In a CI pipeline this means a failed command stops the job by default — no extra error handling required to fail the build when, say, an upload or submission doesn't go through. See [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) for the exceptions, such as `--detached` builds.

## Connecting through a proxy

If your network routes outbound traffic through a proxy — common in corporate or CI environments — the CLI honors the standard proxy environment variables. Set the relevant one before running a command:

```
export HTTPS_PROXY=http://proxy.example.com:8080
```

The CLI picks the proxy based on the protocol of the request it's making:

| Variable                         | Used for                                         |
| -------------------------------- | ------------------------------------------------ |
| `HTTPS_PROXY` (or `https_proxy`) | `https://` requests — what you'll normally need. |
| `HTTP_PROXY` (or `http_proxy`)   | `http://` requests.                              |

The proxy itself can be reached over either protocol, so an HTTP proxy can tunnel HTTPS requests (`HTTPS_PROXY=http://proxy.example.com:8080` is valid). For a proxy that requires credentials, include them in the URL: `http://user:password@proxy.example.com:8080`. If the variable for a request's protocol isn't set, the CLI connects directly.

## Doctor

Diagnose your environment and authentication — Node.js version, login state, and connectivity — with:

```
npx @capawesome/cli doctor
```

This is the first thing to run when a command behaves unexpectedly.

## Next steps

- [Command reference](https://capawesome.io/docs/cloud/cli/commands/index.md) — every command and its options.
- [Examples](https://capawesome.io/docs/cloud/cli/examples/index.md) — practical recipes for builds, Live Updates, and CI.
- [Scripting](https://capawesome.io/docs/cloud/cli/scripting/index.md) — automate the CLI in scripts and CI.
- [Authentication](https://capawesome.io/docs/cloud/cli/authentication/index.md) — log in or use a token.

# Integrations

Connect Capawesome Cloud with external services to streamline your workflow for Live Updates and Native Builds.

For a complete overview of everything Capawesome works with — CI/CD providers, distribution services, notification channels, and supported frameworks — see the [integrations overview](https://capawesome.io/integrations/).

## Git Providers

Git connections are managed per organization on the Git Connections page and reused by your apps.

- **Azure DevOps**

  ______________________________________________________________________

  Connect your Azure DevOps repositories to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/azure-devops/index.md)

- **Bitbucket**

  ______________________________________________________________________

  Connect your Bitbucket repositories to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/bitbucket/index.md)

- **Git (HTTP/S)**

  ______________________________________________________________________

  Connect any Git server over HTTPS to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/git/index.md)

- **Gitea**

  ______________________________________________________________________

  Connect your Gitea repositories to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/gitea/index.md)

- **GitHub**

  ______________________________________________________________________

  Connect your GitHub repositories to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/github/index.md)

- **GitLab**

  ______________________________________________________________________

  Connect your GitLab repositories to Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/gitlab/index.md)

## Notifications

- **Discord**

  ______________________________________________________________________

  Receive webhook notifications in a Discord channel.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/discord/index.md)

- **Microsoft Teams**

  ______________________________________________________________________

  Receive webhook notifications in a Microsoft Teams channel.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/microsoft-teams/index.md)

- **Slack**

  ______________________________________________________________________

  Receive webhook notifications in a Slack channel.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/integrations/slack/index.md)

# Azure DevOps Integration

Connect your Azure DevOps repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- An Azure DevOps account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **Azure DevOps** as the provider.
1. Follow the steps below to authenticate with a personal access token.

### Personal access token (PAT)

Paste a token you create on Azure DevOps.

1. Create an Azure DevOps personal access token for your organization with **Custom defined** scopes:
   - For a read-only connection: **Code (Read)**.
   - To enable [Automations](https://capawesome.io/docs/cloud/automations/index.md): **Code (Read & write)** instead — it also covers managing the repository's service hooks (webhooks).
1. Select **Personal access token (PAT)** as the authentication method and paste the token.

Least privilege

Keep the **Custom defined** scopes instead of granting **Full access**, and select **Code (Read & write)** only if you need automations. Azure DevOps tokens cannot be limited to single repositories.

Organization-scoped tokens

Create the token for the specific organization you want to connect. Because organization-scoped tokens cannot list your organizations ([global tokens are retired as of December 2026](https://devblogs.microsoft.com/devops/retirement-of-global-personal-access-tokens-in-azure-devops/)), you enter the organization name manually when connecting a repository.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the Azure DevOps connection.
1. Select an organization (for personal access token connections, enter the organization name manually), then a project, and finally the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

## Troubleshooting

### Missing organizations

If an Azure DevOps organization does not appear when selecting a repository, ensure the personal access token or personal account has access to the right Azure DevOps organization. Each organization is tied to a specific Microsoft Entra tenant, so sign in with an account from the organization's home tenant, or attach the organization to your default directory.

# Bitbucket Integration

Connect your Bitbucket repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- A Bitbucket Cloud account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **Bitbucket** as the provider.
1. Choose one of the authentication methods below and follow the corresponding steps.

Bitbucket Cloud only

Only Bitbucket Cloud is supported. Bitbucket self-hosted / Data Center instances cannot be connected through this flow, as there is no **Server URL** field for Bitbucket.

### Email & API token (recommended)

Authenticate with your Atlassian account email and an API token you create on Bitbucket. API tokens are available on every Bitbucket plan.

1. Create an [Atlassian API token with scopes](https://id.atlassian.com/manage-profile/security/api-tokens) and select **Bitbucket** as the app:
   - `read:user:bitbucket` — required for every connection.
   - `read:repository:bitbucket` for a read-only connection.
   - To enable [Automations](https://capawesome.io/docs/cloud/automations/index.md): also add `read:webhook:bitbucket` and `write:webhook:bitbucket`.
1. Select **Email & API token** as the authentication method, enter your Atlassian account **email**, and paste the token.

Least privilege

An API token inherits your account's repository access, so grant only the scopes listed above. To limit the connection to a single workspace, use a workspace access token instead.

API tokens expire

Atlassian API tokens have a maximum lifetime of one year. When the token expires, the connection stops working until you update it with a new token.

App passwords are deprecated

Bitbucket [app passwords are being removed](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). Create an API token with scopes instead.

### Workspace access token

Paste a workspace access token you create on Bitbucket. Workspace access tokens require a [Bitbucket Premium plan](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), do not expire, and belong to the workspace instead of a personal account.

1. Create a Bitbucket workspace access token (**Workspace settings → Access tokens**) with these permissions:
   - **Repositories → Read** for a read-only connection.
   - To enable [Automations](https://capawesome.io/docs/cloud/automations/index.md): also add **Repositories → Admin** (required to manage webhooks).
1. Select **Workspace access token** as the authentication method and paste the token.

Least privilege

Create the token in the workspace that holds your app's repository and add **Repositories → Admin** only if you need automations.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the Bitbucket connection.
1. Enter your **workspace** slug — from `bitbucket.org/<workspace>`, since Bitbucket can't list your workspaces — then select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

# Discord Integration

Receive real-time [webhook](https://capawesome.io/docs/cloud/webhooks/index.md) notifications from Capawesome Cloud directly in a Discord channel.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account with an app created.
- A Discord server with the **Manage Webhooks** permission.

## Setup

Follow these steps to set up Discord notifications for your app:

1. Create a webhook in your Discord server by navigating to **Server Settings > Integrations > Webhooks** and clicking **New Webhook**. Select the channel you want notifications posted to and copy the webhook URL. For detailed instructions, see the [Discord documentation](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).
1. Navigate to the [Webhooks](https://console.cloud.capawesome.io/apps/_/webhooks) page in the Capawesome Cloud Console. Create a new webhook (or edit an existing one) and paste the Discord webhook URL.
1. Set the **Format** to **Discord**.
1. Select the [events](https://capawesome.io/docs/cloud/webhooks/#events) you want to receive and save the webhook.

That's it. Capawesome Cloud sends Discord-compatible messages to the configured URL. Notifications will appear in your selected channel whenever the configured events are triggered.

For more details on supported events, payloads, signature verification, and delivery history, see the [Webhooks](https://capawesome.io/docs/cloud/webhooks/index.md) documentation.

# Git (HTTP/S) Integration

Connect any Git repository reachable over HTTP or HTTPS to Capawesome Cloud to build and automate your app directly from source. Use this provider for any Git server that is not GitHub, GitLab, Bitbucket, Azure DevOps, or Gitea. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- A Git repository reachable over HTTP or HTTPS (HTTPS recommended), and credentials for it if it is private.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **Git (HTTP/S)** as the provider.
1. Follow the steps below to authenticate with a username and password.

### Username & password

Git (HTTP/S) connections authenticate with basic auth against a plain smart-HTTP(S) remote.

1. Select **Username & password** as the authentication method.
1. Enter the username and password for the repository. Leave both empty for public repositories.

Least privilege

Use credentials that grant read-only access to just the repository you connect — for example a dedicated deploy user or a repository-scoped token — instead of your personal account password.

Token-only providers

Some Git hosts authenticate with a token instead of a username and password. On GitHub, for example, leave the **username** empty and paste a personal access token (PAT) with repository read access as the **password**.

## Connect a repository to your app

Because there is no provider API to browse repositories, you paste the repository URL directly:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the Git (HTTP/S) connection.
1. Paste the full **Clone URL** of the repository (e.g. `https://git.example.com/team/my-app.git`).

You can also connect a repository during **Create app** (on the **Git** tab).

No automations

Git (HTTP/S) connections don't support webhooks, so [Automations](https://capawesome.io/docs/cloud/automations/index.md) are unavailable. Commit details are also limited to the commit SHA — no author, message, or branch information, and no commit links.

# Gitea Integration

Connect your Gitea repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- A Gitea account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **Gitea** as the provider.
1. Follow the steps below to authenticate with a personal access token.

### Personal access token (PAT)

Gitea connections authenticate with a personal access token.

1. Create a Gitea access token (**Settings → Applications**) with these scopes:
   - **User → Read** (`read:user`) and **Organization → Read** (`read:organization`) — required for every connection.
   - **Repository → Read** (`read:repository`) for a read-only connection, or **Repository → Read and Write** (`write:repository`) to enable [Automations](https://capawesome.io/docs/cloud/automations/index.md) (also covers cloning).
1. Select **Personal access token (PAT)** as the authentication method and paste the token.
1. Because Gitea is typically self-hosted, enable **Self-hosted or enterprise instance** and enter your Gitea **Server URL**. Leave it empty only if you use a Gitea cloud instance such as `gitea.com`.

Least privilege

An access token covers every repository your account can access, so grant only the scopes listed above. Select **Repository → Read and Write** only if you need automations.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the Gitea connection.
1. Select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

# GitHub Integration

Connect your GitHub repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- A GitHub account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **GitHub** as the provider.
1. Choose one of the authentication methods below and follow the corresponding steps.

Already using GitHub via OAuth?

Existing GitHub connections created with the personal account (OAuth) method keep working. You can upgrade them to the GitHub App at any time from the connection's edit dialog. Read the [Git integration revamp announcement](https://capawesome.io/blog/git-integration-revamp-in-capawesome-cloud/index.md) to learn why we recommend the switch.

### GitHub App (recommended)

The GitHub App is the recommended method. Repository access is managed on GitHub, and no tokens are stored in Capawesome Cloud. Each connection is tied to a single GitHub user or organization account — to use repositories from multiple accounts, create a separate connection for each.

1. Select **GitHub App** as the authentication method.
1. Click **Continue to GitHub**.
1. Install and configure the Capawesome Cloud GitHub App on your GitHub user or organization account, and select which repositories it can access.
1. After confirming on GitHub, you are returned to the console and the connection is created.

To change which repositories the app can access later, use **Configure on GitHub** — repository access is always managed on GitHub.

Least privilege

Select only the repositories Capawesome Cloud needs to build your app instead of granting access to all repositories.

### Personal access token (PAT)

Paste a token you create on GitHub. This works for GitHub.com and, via the **Server URL** field, GitHub Enterprise Server.

1. Create a GitHub personal access token. GitHub offers two token types:
   - **Fine-grained token** (recommended): grant **Contents: Read-only** (**Metadata: Read-only** is added automatically). To enable [Automations](https://capawesome.io/docs/cloud/automations/index.md), also grant **Webhooks: Read and write**.
   - **Classic token**: grant the `repo` scope — it already includes webhook management. For public repositories only, `public_repo` is enough (add `admin:repo_hook` for automations).
1. Select **Personal access token (PAT)** as the authentication method and paste the token.
1. For **GitHub Enterprise Server** (self-hosted), enable **Self-hosted or enterprise instance** and enter your server's **Server URL**.

Least privilege

Prefer a fine-grained token: restrict it to the repositories needed for the build and grant only the permissions listed above. Classic tokens cannot be limited to single repositories.

Organization repositories

For a repository owned by an organization, a classic token may need to be authorized for SSO, and a fine-grained token may require approval by an organization owner.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the GitHub connection.
1. Select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

## Troubleshooting

### Organization repository not visible

If an organization's repositories do not appear when selecting a repository, the connection may not have access to them. Configure repository access for the Capawesome Cloud GitHub App on GitHub, or re-authorize the personal account so it can see the organization's repositories.

# GitLab Integration

Connect your GitLab repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and an organization (owner or admin role to manage Git connections).
- A GitLab account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page and click **Create Git connection**.
1. Select **GitLab** as the provider.
1. Follow the steps below to authenticate with a personal access token.

### Personal access token (PAT)

Paste a token you create on GitLab. This works for GitLab.com and, via the **Server URL** field, self-managed GitLab.

1. Create a GitLab personal access token — choose a **legacy token**, not a **fine-grained** token. Always select the `read_user` scope, plus:
   - For a read-only connection: the `read_api` and `read_repository` scopes.
   - To enable [Automations](https://capawesome.io/docs/cloud/automations/index.md): the `api` scope (it covers both cloning and managing the project's webhooks). Your account also needs the **Maintainer** or **Owner** role on the project.
1. Select **Personal access token (PAT)** as the authentication method and paste the token.
1. For **self-managed GitLab**, enable **Self-hosted or enterprise instance** and enter your server's **Server URL**.

Least privilege

A personal access token covers every project your account can access, so grant only the scopes listed above. Select the `api` scope only if you need automations.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git) page and click **Connect Git repository**.
1. Select the GitLab connection.
1. Select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

# Microsoft Teams Integration

Receive real-time [webhook](https://capawesome.io/docs/cloud/webhooks/index.md) notifications from Capawesome Cloud directly in a Microsoft Teams channel.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account with an app created.
- A Microsoft Teams workspace with permission to create Workflows.

## Setup

Follow these steps to set up Microsoft Teams notifications for your app:

1. Create an incoming webhook in Teams using Workflows. You can either use a webhook template (select **More options** next to a channel > **Workflows**) or create one from scratch using the **When a Teams webhook request is received** trigger. After creating the workflow, copy the generated HTTP POST URL. For detailed instructions, see the [Microsoft documentation](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498).
1. Navigate to the [Webhooks](https://console.cloud.capawesome.io/apps/_/webhooks) page in the Capawesome Cloud Console. Create a new webhook (or edit an existing one) and paste the Teams webhook URL.
1. Set the **Format** to **Microsoft Teams**.
1. Select the [events](https://capawesome.io/docs/cloud/webhooks/#events) you want to receive and save the webhook.

That's it. Capawesome Cloud sends messages as Adaptive Cards to the configured URL. Notifications will appear in your selected channel whenever the configured events are triggered.

Tip

If you need to retrieve the webhook URL later, you can find it by editing the workflow in Microsoft Teams.

For more details on supported events, payloads, signature verification, and delivery history, see the [Webhooks](https://capawesome.io/docs/cloud/webhooks/index.md) documentation.

# Slack Integration

Receive real-time [webhook](https://capawesome.io/docs/cloud/webhooks/index.md) notifications from Capawesome Cloud directly in a Slack channel.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account with an app created.
- A Slack workspace where you have permission to install apps.

## Setup

Follow these steps to set up Slack notifications for your app:

1. Create a Slack app with an incoming webhook by following the [Slack documentation](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/). Enable **Incoming Webhooks** in your app settings, add a new webhook to a workspace, select the target channel, and copy the generated webhook URL (e.g. `https://hooks.slack.com/services/...`).
1. Navigate to the [Webhooks](https://console.cloud.capawesome.io/apps/_/webhooks) page in the Capawesome Cloud Console. Create a new webhook (or edit an existing one) and paste the Slack webhook URL.
1. Set the **Format** to **Slack**.
1. Select the [events](https://capawesome.io/docs/cloud/webhooks/#events) you want to receive and save the webhook.

That's it. Capawesome Cloud sends Slack-compatible messages to the configured URL. Notifications will appear in your selected channel whenever the configured events are triggered.

Warning

Your Slack webhook URL contains a secret. Do not share it publicly or commit it to version control. Slack actively searches for and revokes leaked webhook URLs.

For more details on supported events, payloads, signature verification, and delivery history, see the [Webhooks](https://capawesome.io/docs/cloud/webhooks/index.md) documentation.

# Live Updates

Use [Capawesome Cloud](/) to deliver updates to your Capacitor or Cordova app in real-time. Ship critical bug fixes, new features, and content updates instantly without submitting a native update to the app stores.

## Features

- 📱 **Cross-Platform**: Works with Android and iOS apps built with Capacitor or Cordova, and with [Electron desktop apps](https://capawesome.io/docs/cloud/live-updates/electron/index.md) built with Capacitor.
- 📦 **Bundle Management**: Upload, download and delete bundles.
- 📺 **Channel Support**: Deliver bundles via multiple channels.
- 🚀 **Rollout**: Gradually roll out new bundles to gather valuable feedback.
- 💾 **Self-Hosting**: You can either host your bundles yourself or upload them to Capawesome Cloud.
- 📈 **Analytics**: Get insights into the number of your monthly active users.
- 💳 **Payments**: Upgrade and downgrade your plan at any time with monthly and annual payments.
- 💼 **Enterprise**: Deploy live updates to millions of users in real-time.
- 🔒 **Security**: Sign bundles with a private key to ensure that only you can publish updates.
- 📚 **Documentation**: Comprehensive documentation to help you get started.

## Getting Started

- **Setup Live Updates**

  ______________________________________________________________________

  Get started by installing the Live Update plugin and publishing your first update.

  ______________________________________________________________________

  [Getting Started](https://capawesome.io/docs/cloud/live-updates/setup/index.md)

## Documentation

- **How It Works**

  ______________________________________________________________________

  Understand how Live Updates deliver new bundles to your app.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/how-it-works/index.md)

- **Publish a Live Update**

  ______________________________________________________________________

  Build your web assets and ship them as a new bundle.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/publish/index.md)

- **Bundles**

  ______________________________________________________________________

  Learn how to create and manage bundles for your app.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/bundles/index.md)

- **Channels**

  ______________________________________________________________________

  Learn how to create and manage channels for your app.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/channels/index.md)

- **Update Strategies**

  ______________________________________________________________________

  Choose how and when updates are downloaded and applied.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md)

- **Rollouts**

  ______________________________________________________________________

  Gradually roll out a bundle to a percentage of your users.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md)

- **Rollbacks**

  ______________________________________________________________________

  Revert to a previous bundle when an update goes wrong.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md)

- **Code Signing**

  ______________________________________________________________________

  Sign your bundles so only you can publish updates.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md)

- **Security**

  ______________________________________________________________________

  Harden your update path, from signing keys to API tokens.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/security/index.md)

- **Self-Hosting**

  ______________________________________________________________________

  Host your bundles yourself instead of on Capawesome Cloud.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md)

- **Request Proxying**

  ______________________________________________________________________

  Route Live Update API traffic through a reverse proxy you control.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/request-proxying/index.md)

- **Devices**

  ______________________________________________________________________

  Learn how to manage devices for your app.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/devices/index.md)

- **Logs**

  ______________________________________________________________________

  Learn how to debug your app using logs.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/logs/index.md)

- **Troubleshooting**

  ______________________________________________________________________

  Find solutions when an update doesn't reach your device.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/troubleshooting/index.md)

- **CI/CD Integrations**

  ______________________________________________________________________

  Publish live updates from GitHub Actions, GitLab CI, and more.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/integrations/index.md)

- **FAQ**

  ______________________________________________________________________

  Find answers to frequently asked questions about Capawesome Cloud Live Updates.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/live-updates/faq/index.md)

## Guides

Here are some guides to help you get started with Capawesome Cloud Live Updates:

- [Announcing the Capacitor Live Update Plugin](https://capawesome.io/blog/announcing-the-capacitor-live-update-plugin/index.md)
- [How to restrict Capacitor Live Updates to Native Versions](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/index.md)
- [How to gradually roll out Capacitor Live Updates](https://capawesome.io/blog/how-to-gradually-roll-out-capacitor-live-updates/index.md)
- [Capacitor App Updates: The Complete Guide](https://capawesome.io/blog/capacitor-app-update-guide/index.md)

______________________________________________________________________

1. In order to use our servers in Germany, the Live Update SDK must be configured accordingly. Further information can be found in the [Privacy](https://capawesome.io/docs/cloud/live-updates/privacy/index.md) section. [↩](#fnref:1 "Jump back to footnote 1 in the text")

# Binary-Compatible Changes

The single most important rule with Live Updates: **you can only update what already exists in the native binary.** Changes that don't touch native code are called *binary-compatible* and can ship as a Live Update. Anything else needs a real app store release.

Understanding this rule comes down to understanding how your app is built, so let's start there.

## The two layers of your app

Every Capacitor and Cordova app is made up of two distinct layers:

A Capacitor or Cordova app consists of a native layer and a web layer.

- **The native layer** is the compiled binary your users install from the App Store or Google Play. It contains the WebView, the native plugins, and the platform code that bridges JavaScript to native APIs. It can only be replaced by shipping a new build to the stores.
- **The web layer** is everything that runs inside that WebView — your HTML, CSS, JavaScript, and static assets. These files are *not* compiled into the binary; they sit on disk and are loaded at runtime.

On the desktop, the native layer is the packaged Electron app — the `electron/` project and the plugins' Electron implementations — and the same rules apply (see [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/index.md)).

A Live Update replaces the **web layer only**. The native binary stays exactly as it was installed. That's what makes over-the-air updates possible — and it's also the source of the one rule you have to respect.

## What counts as binary-compatible

A useful mental model: if your change only modifies files inside your web project — your `src/` and its build output — and doesn't add, remove, or upgrade a plugin or any native code or configuration, it's binary-compatible and can ship as a Live Update.

| Change                                            | Binary-compatible? | Where it ships |
| ------------------------------------------------- | ------------------ | -------------- |
| HTML, CSS, JavaScript                             | Yes                | Live Update    |
| Images, fonts, JSON, web-only assets              | Yes                | Live Update    |
| Web framework upgrade (Angular, React, Vue, …)    | Yes                | Live Update    |
| Pure JavaScript dependency added or updated       | Yes                | Live Update    |
| Capacitor or Cordova plugin added or removed      | No                 | App store      |
| Capacitor or Cordova plugin major version bump    | Usually no         | App store      |
| Native code (Java/Kotlin/Swift/Objective-C)       | No                 | App store      |
| `AndroidManifest.xml`, `Info.plist`, entitlements | No                 | App store      |
| App icon, splash screen                           | No                 | App store      |

When in doubt, ask yourself a single question: *does this change require recompiling the native project?* If the answer is yes, it has to go through the app store.

## Why it matters

Picture a user running version 5 of your native app. You publish a web bundle that calls a method on a plugin you only added in version 6. Because the native layer on that device still belongs to version 5, the method doesn't exist — and when the bundle tries to call it, the app **crashes on launch**. The user can't open the app to receive a fix, so their only way out is deleting and reinstalling from the store.

This is by far the most common production failure with Live Updates, and it's entirely preventable.

## How to prevent it

Bind each web bundle to the range of native versions it is compatible with, so a bundle only ever reaches devices that can run it. Capawesome Cloud gives you two ways to enforce this, and the table below summarizes how they compare:

|                             | Versioned channels (recommended)                             | Versioned bundles                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| How it works                | One channel per native version (e.g. `production-<version>`) | One channel, each bundle tagged with a native version range                                                                                                              |
| Where it's configured       | Natively at build time                                       | Per upload, via CLI flags                                                                                                                                                |
| Adding a new native version | Automatic — the new build subscribes to its own channel      | Nothing to change; set the range on each upload                                                                                                                          |
| Rollout accuracy            | Accurate — only compatible devices count                     | Skewed — incompatible devices still count toward the percentage (see [Rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/#rollout-percentage-calculation)) |

Both approaches are documented in detail on their own pages:

- **[Versioned channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels)** (recommended) give each native release its own channel, so a bundle uploaded for one native version is never delivered to a device running another.
- **[Versioned bundles](https://capawesome.io/docs/cloud/live-updates/bundles/#versioned-bundles)** keep a single channel and attach a native version range to each upload instead.

When in doubt, choose versioned channels — they require no per-upload bookkeeping and keep [rollout](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md) percentages accurate.

# Reduce Update Size

Smaller bundles download faster and fail less often on flaky connections, and they keep your [data transfer](https://capawesome.io/docs/cloud/live-updates/limits/index.md) down. There are two levers: shrink the assets, and choose the right delivery format.

## Optimize your assets

A few changes cover most of the wins:

- **Drop source maps.** They're often the majority of a bundle's size and don't belong in production downloads. In Vite, set `build.sourcemap: false`; in Angular, build with `--source-map=false`. If you need them for error tracking, upload them to your error-tracking service separately.
- **Move heavy static assets to a CDN.** Hero images, marketing media, and downloadable files that don't have to ship inside the bundle should be served from a CDN and loaded on demand.
- **Audit your bundle.** Tree-shaking and minification are handled by most modern build tools, but a tool like `rollup-plugin-visualizer` or `webpack-bundle-analyzer` helps find unexpectedly large dependencies.

## Choose the delivery format

### Zip (recommended)

By default, the whole web folder is compressed into a single `.zip` and uploaded. The device downloads one compressed file and extracts it. This is almost always the right choice — compression typically halves the size and the download is a single request.

### Delta updates (manifest)

Live Updates can be smaller if only modified files are downloaded. For this, each bundle requires a **manifest** — a JSON file containing hashes of the files in the bundle. When updating, the manifest of the new bundle is compared with the current one, and only the changed files are downloaded. Delta updates aren't available on [Electron](https://capawesome.io/docs/cloud/live-updates/electron/index.md) — desktop apps always receive `zip` bundles.

Try the zip artifact type first

Delta updates are only beneficial if your app contains large files that rarely change. Most modern frameworks generate content-hashed filenames on each build, causing every file to look changed — which makes delta comparison ineffective and can result in hundreds of individual file requests instead of one zip download. Start with `zip` and only switch to `manifest` if you have a clear, measured need.

#### Generate the manifest file

Generate a manifest with the [`apps:liveupdates:generatemanifest`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesgeneratemanifest) command, after building your web assets but before copying them to the native projects:

```
npm run build
npx @capawesome/cli apps:liveupdates:generatemanifest --path www
```

The easiest way to keep it in sync is to add it to your build script:

```
{
  "scripts": {
    "build": "ng build && npx @capawesome/cli apps:liveupdates:generatemanifest --path www"
  }
}
```

Manifest required on both sides

Delta updates only work when two manifests are available for comparison. Always include the manifest file in your native releases — if one is missing, all files are downloaded.

#### Upload a delta bundle

Upload with the `manifest` artifact type so files are uploaded individually rather than as a single zip:

```
npx @capawesome/cli apps:liveupdates:upload --artifact-type manifest
```

CLI only

Delta updates can only be created with the CLI, not the Console.

# Bundles

A **bundle** (a "Live Update") is the packaged web assets — HTML, CSS, JavaScript, images — of your app, deployed to a [channel](https://capawesome.io/docs/cloud/live-updates/channels/index.md) in Capawesome Cloud. Because a bundle contains only web assets and no native code, it can be delivered to your users without an app store review. See [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for exactly what a bundle can and cannot change.

For how bundles relate to channels, deployments, and devices — and the full path from publishing to applying an update — see [How Live Updates Work](https://capawesome.io/docs/cloud/live-updates/how-it-works/index.md).

## Create a bundle

There are two ways to get a bundle into Capawesome Cloud:

- **Build in the cloud or upload** from your machine — see [Publish an update](https://capawesome.io/docs/cloud/live-updates/publish/index.md).
- **Register a self-hosted bundle** by URL — see [Self-host bundles](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md).

## Custom properties

You can attach custom properties to a bundle — for example a version number or release notes — and read them in your app.

```
npx @capawesome/cli apps:liveupdates:upload --custom-property key1=value1 --custom-property key2=value2
```

Read them with `fetchLatestBundle()`:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const { customProperties } = await LiveUpdate.fetchLatestBundle();
// customProperties = { key1: "value1", key2: "value2" }
```

```
const { customProperties } = await cordova.plugins.LiveUpdate.fetchLatestBundle();
// customProperties = { key1: "value1", key2: "value2" }
```

Custom properties can be updated at any time from the [Console](https://console.cloud.capawesome.io/) or the [CLI](https://capawesome.io/docs/cloud/cli/index.md).

## Versioned bundles

A Live Update may only reach devices whose native binary can run it — see [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for why this matters and how it compares to [versioned channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels). Versioned bundles enforce this without extra channels: attach a native version range to each upload, and Capawesome Cloud only serves the bundle to devices inside that range. Use the `--android-min` / `--android-max` / `--ios-min` / `--ios-max` flags on [`apps:liveupdates:upload`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesupload):

```
npx @capawesome/cli apps:liveupdates:upload \
  --channel production \
  --android-min 6 \
  --ios-min 6
```

This bundle reaches only devices on Android `versionCode` 6 or higher and iOS `CFBundleVersion` 6 or higher. To exclude a single native version instead of setting a range, use `--android-eq` / `--ios-eq` — the bundle is then served to every device except those on the exact version code you specify.

For example, suppose a web bundle is compatible with Android `versionCode` 4 through 6, but version 5 already ships that exact bundle baked into its native binary. You can target the range and skip version 5 in one upload:

```
npx @capawesome/cli apps:liveupdates:upload \
  --channel production \
  --android-min 4 \
  --android-max 6 \
  --android-eq 5
```

Devices on `versionCode` 4 and 6 receive the update, while version 5 is left alone because it already includes the bundle. The same flags are available on [`apps:liveupdates:register`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesregister) for self-hosted bundles. For Electron desktop apps, use `--electron-min` / `--electron-max` / `--electron-eq` with the Electron app version instead — see [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/#versioned-bundles).

## Next steps

- [Publish an update](https://capawesome.io/docs/cloud/live-updates/publish/index.md) — ship a new bundle to your users.
- [Manage channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) — control which devices receive which bundles.
- [How Live Updates Work](https://capawesome.io/docs/cloud/live-updates/how-it-works/index.md) — see how bundles fit into the bigger picture.

# Subscribe to a Channel

Every device receives Live Updates from a single [channel](https://capawesome.io/docs/cloud/live-updates/channels/index.md). This page covers how your app chooses which channel to subscribe to.

## The default channel

Every app starts with a channel named `default`. When your app doesn't request a specific channel, it receives updates from this one. The default channel exists mainly as a **fallback** to make getting started easy — you can publish your first update and watch it land without configuring any channels.

For production, we recommend moving to **versioned channels** — one channel per native app version — so a bundle only ever reaches devices that can run it. See [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for why this matters, and the next section for how to set it up.

## Set the channel natively (recommended)

The cleanest approach is to configure the channel **natively at build time**. Your app code then doesn't need to manage channels at all, and you can derive the channel from the native version code to get versioned channels for free. See [Get Started](https://capawesome.io/docs/cloud/live-updates/setup/#make-updates-version-compatible) for the Android and iOS configuration, and [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/#versioned-channel) for Electron.

## Select the channel at runtime

If you need to choose the channel dynamically — for example, to opt a user into a `beta` channel — pass the `channel` to the method that fetches updates. Passing it explicitly at the call site keeps the selected channel unambiguous.

### With `sync()`

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.sync({ channel: "beta" });
```

```
await cordova.plugins.LiveUpdate.sync({ channel: "beta" });
```

### With `fetchLatestBundle()`

If you handle the [update lifecycle manually](https://capawesome.io/docs/cloud/live-updates/manual-updates/index.md), pass the channel to `fetchLatestBundle()` instead:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const result = await LiveUpdate.fetchLatestBundle({ channel: "beta" });
```

```
const result = await cordova.plugins.LiveUpdate.fetchLatestBundle({ channel: "beta" });
```

### With `setChannel()`

You can also set the channel once with `setChannel()`, which persists it for all subsequent calls:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.setChannel({ channel: "beta" });
```

```
await cordova.plugins.LiveUpdate.setChannel({ channel: "beta" });
```

Prefer passing the channel directly

We don't recommend `setChannel()`. Passing the `channel` to `sync()` or `fetchLatestBundle()` on every call keeps the selected channel explicit at the call site and avoids relying on hidden, persisted state.

### Derive the channel from the version code

A common pattern is to compute the channel from the native version code, so updates stay [version-compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md):

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const { versionCode } = await LiveUpdate.getVersionCode();
await LiveUpdate.sync({ channel: `production-${versionCode}` });
```

```
const { versionCode } = await cordova.plugins.LiveUpdate.getVersionCode();
await cordova.plugins.LiveUpdate.sync({ channel: `production-${versionCode}` });
```

## Next steps

- [Manage Channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) — create and configure channels for staging and production.
- [Choose an Update Strategy](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md) — control when updates are downloaded and applied.

# Manage Channels

A **channel** is a named stream of Live Updates that a group of devices subscribes to. Channels let you deliver different bundles to different groups — for example a `staging` channel for testers and a `production` channel for everyone else, or one channel per native version to keep updates [version-compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md).

Every device receives updates from exactly one channel. How a device chooses its channel is covered in [Subscribe to a channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md); this page covers creating and managing the channels themselves. If you don't need per-device channels, [set a default channel](#default-channel) that is used automatically.

## Default Channel

Each app has a default channel named `default` to simplify the initial setup. This channel is used when no specific channel is specified during the bundle upload process or when fetching updates in your app using the [Live Update SDK](https://capawesome.io/docs/cloud/live-updates/setup/index.md). A default channel is not required for your app to function. You can rename, delete, or [set another channel as the default channel](#set-default-channel) at any time.

## Protected Channels

Channels can be marked as "protected" to enhance the security of your live updates. When a channel is protected, all builds associated with that channel must be code-signed before they can be distributed to users. This ensures that only authorized builds are delivered through the protected channel. Read more about [Code Signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) in Capawesome Cloud.

## Manage Channels

You can manage channels associated with your app using the Capawesome CLI or the Capawesome Cloud Console.

### Create a channel

To create a channel using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:channels:create`](https://capawesome.io/docs/cloud/cli/commands/#appschannelscreate) command:

```
npx @capawesome/cli apps:channels:create
```

You will be prompted to select the app you want to create the channel for and to provide the name of the channel. The CLI will then create the channel in the Capawesome Cloud.

To create a channel using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to create the channel for, and click on the [Channels](https://console.cloud.capawesome.io/apps/_/channels) menu item under the "Live Updates" section in the sidebar. Next, click on the "Create channel" button and enter the name of the channel you want to create.

### Update a channel

To update a channel using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:channels:update`](https://capawesome.io/docs/cloud/cli/commands/#appschannelsupdate) command:

```
npx @capawesome/cli apps:channels:update
```

You will be prompted to select the app you want to update the channel for and to provide the ID of the channel. The CLI will then update the channel in the Capawesome Cloud based on the provided information.

To update a channel using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to update the channel for, and click on the [Channels](https://console.cloud.capawesome.io/apps/_/channels) menu item under the "Live Updates" section in the sidebar. Next, select the channel you want to update. In the menu, click on the "Edit" button to update the name and settings of the channel.

### Delete a channel

To delete a channel using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:channels:delete`](https://capawesome.io/docs/cloud/cli/commands/#appschannelsdelete) command:

```
npx @capawesome/cli apps:channels:delete
```

You will be prompted to select the app you want to delete the channel for and to provide the name of the channel. The CLI will then delete the channel from the Capawesome Cloud.

To delete a channel using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to delete the channel for, and click on the [Channels](https://console.cloud.capawesome.io/apps/_/channels) menu item under the "Live Updates" section in the sidebar. Next, select the channel you want to delete. In the menu, click on the "Delete" button to delete the channel.

### Set default channel

To set a channel as the [default channel](#default-channel) using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to set the default channel for, and click on the [Settings](https://console.cloud.capawesome.io/apps/_/settings) menu item in the sidebar. Next, in the "Channels" section, enable the "Default channel" toggle, select the channel you want to set as the default channel from the dropdown menu, and click on the "Save" button.

## Channel Discovery

Channel discovery allows the Live Update SDK to fetch the list of available channels without requiring authentication. This is useful for apps that want to let developers or QA select a channel from a list of available channels (e.g. a beta channel).

To enable channel discovery using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to enable channel discovery for, and click on the [Settings](https://console.cloud.capawesome.io/apps/_/settings) menu item in the sidebar. Next, in the "Channels" section, enable the "Channel discovery" toggle and click on the "Save" button.

Once enabled, you can use the `fetchChannels(...)` method of the Live Update SDK to fetch the list of available channels (available for both the Capacitor and Cordova plugins).

## Versioned channels

A Live Update may only reach devices whose native binary can run it — see [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for why this matters and how it compares to [versioned bundles](https://capawesome.io/docs/cloud/live-updates/bundles/#versioned-bundles).

Versioned channels are the recommended way to enforce this: give each native release its own channel derived from its native version (e.g. `production-<version>`, where `<version>` is the Android `versionCode`, iOS `CFBundleVersion`, or Electron app version), so a bundle uploaded for one native version is never delivered to a device running another. You configure the channel natively at build time, which means every release automatically ships pinned to its own channel with nothing to remember on each upload.

On Android, add a resource value in `android/app/build.gradle`:

android/app/build.gradle

```
android {
    defaultConfig {
        resValue "string", "capawesome_live_update_default_channel",
                 "production-" + defaultConfig.versionCode
    }
}
```

On iOS, add a key to `ios/App/App/Info.plist`:

ios/App/App/Info.plist

```
<key>CapawesomeLiveUpdateDefaultChannel</key>
<string>production-$(CURRENT_PROJECT_VERSION)</string>
```

On Electron, set `defaultChannel` in `electron/capacitor.electron.config.ts` — see [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/#versioned-channel).

On Android, set the channel via a `build-extras.gradle` file included through your `config.xml`:

build-extras.gradle

```
android {
    applicationVariants.all { variant ->
        variant.resValue "string", "capawesome_live_update_default_channel",
                         "production-" + variant.versionCode
    }
}
```

On iOS, add the channel key to your `Info.plist` via `config.xml`:

config.xml

```
<platform name="ios">
  <config-file target="*-Info.plist" parent="CapawesomeLiveUpdateDefaultChannel">
    <string>production-$(CURRENT_PROJECT_VERSION)</string>
  </config-file>
</platform>
```

Every native release now ships pinned to its own channel, and uploads to `production-<version>` only reach matching devices. To override the channel at runtime instead of at build time, see [Subscribe to a channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md).

## Bonus: Video Walkthrough

# Sign Your Bundles

Code signing lets your app verify the **authenticity** and **integrity** of every Live Update before applying it — so only bundles you produced, unmodified, are ever installed. Even though delivery is over HTTPS, signing is defense in depth, and is required for [protected channels](https://capawesome.io/docs/cloud/live-updates/channels/#protected-channels).

The mechanism is a standard RSA key pair: you sign each bundle with your **private** key when uploading, and your app verifies the signature with the embedded **public** key.

## Generate the key pair

Generate a key pair with the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md):

```
npx @capawesome/cli apps:liveupdates:generatesigningkey
```

This creates `private.pem` (keep it secret) and `public.pem`. You can customize the paths and key size:

```
npx @capawesome/cli apps:liveupdates:generatesigningkey --private-key-path=./keys/private.pem --public-key-path=./keys/public.pem --key-size=4096
```

Keep your private key safe

Never commit your private key to version control — add `private.pem` to your `.gitignore`.

## Create a signed bundle

Pass the private key with `--private-key` when uploading:

```
npx @capawesome/cli apps:liveupdates:upload --private-key private.pem
```

## Configure the public key

Add the public key to your app's configuration so it can verify signatures. The `generatesigningkey` command prints the value preformatted (no line breaks) so you can paste it directly.

capacitor.config.json

```
{
  "plugins": {
    "LiveUpdate": {
      "publicKey": "-----BEGIN PUBLIC KEY-----MIGf...IDAQAB-----END PUBLIC KEY-----"
    }
  }
}
```

config.xml

```
<preference name="PUBLIC_KEY" value="-----BEGIN PUBLIC KEY-----MIGf...IDAQAB-----END PUBLIC KEY-----" />
```

From now on, your app verifies every downloaded bundle and refuses to apply anything not signed by your private key. We strongly recommend enabling code signing in production, especially if you operate multiple channels or [self-host](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) your bundles.

No line breaks

The public key value must **not** contain line breaks. The CLI formats it correctly, so copy it directly from the output.

## Bonus: Video Walkthrough

## Next steps

- [Protect your channels](https://capawesome.io/docs/cloud/live-updates/channels/#protected-channels) — require signed bundles before anything can be distributed.
- [Self-host your bundles](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) — keep your web artifacts on your own infrastructure, combined with code signing.
- [Security](https://capawesome.io/docs/cloud/live-updates/security/index.md) — the rest of the checklist for a production Live Update setup.

# Manage Devices

A **device** is a unique installation of your app that has connected to Capawesome Cloud to check for Live Updates. Each device is identified by a unique device ID and receives updates from a single channel. Managing devices lets you monitor and control how updates are distributed.

## Channel assignment

A device's channel is chosen by your app. Pass the `channel` directly to `sync()` (or `fetchLatestBundle()`) at the call site — for example, deriving it from the native version code so updates stay [version-compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md):

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const { versionCode } = await LiveUpdate.getVersionCode();
await LiveUpdate.sync({ channel: `production-${versionCode}` });
```

```
const { versionCode } = await cordova.plugins.LiveUpdate.getVersionCode();
await cordova.plugins.LiveUpdate.sync({ channel: `production-${versionCode}` });
```

For the different ways to select a channel — including the recommended native default channel — see [Subscribe to a channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md).

## Manage Devices

You can manage devices associated with your app using the Capawesome CLI or the Capawesome Cloud Console.

### Create a device

Devices are created automatically when a user checks for a live update for the first time by calling the `fetchLatestBundle(...)` or `sync()` method from the [Live Update SDK](https://capawesome.io/docs/cloud/live-updates/setup/index.md).

### Force a channel

By default, devices receive live updates from the channel set by the Live Update SDK. You can override this by forcing a specific channel on a device. When a channel is forced, the SDK-selected channel is ignored and the device receives updates exclusively from the forced channel instead. This can be useful for debugging, testing, or manually managing the channel for a specific device. Read our [blog post](https://capawesome.io/blog/capawesome-cloud-forced-channel-assignments/index.md) for more details and use cases.

To force a channel on a device using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:devices:forcechannel`](https://capawesome.io/docs/cloud/cli/commands/#appsdevicesforcechannel) command:

```
npx @capawesome/cli apps:devices:forcechannel
```

You will be prompted to select the app and provide the device ID and channel name.

To remove the forced channel and return to normal SDK behavior, use the [`apps:devices:unforcechannel`](https://capawesome.io/docs/cloud/cli/commands/#appsdevicesunforcechannel) command:

```
npx @capawesome/cli apps:devices:unforcechannel
```

To force a channel on a device using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to force the channel for, and click on the [Devices](https://console.cloud.capawesome.io/apps/_/devices) menu item under the "Live Updates" section in the sidebar. Next, click on "Edit" in the "Actions" menu of the device you want to force a channel for. In the dialog, select the channel you want to force and confirm the changes.

### Delete a device

A device can be deleted at any time.

To delete a device using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:devices:delete`](https://capawesome.io/docs/cloud/cli/commands/#appsdevicesdelete) command:

```
npx @capawesome/cli apps:devices:delete
```

You will be prompted to select the app you want to delete the device for and to provide the ID of the device. The CLI will then delete the device from the Capawesome Cloud.

To delete a device using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to delete the device for, and click on the [Devices](https://console.cloud.capawesome.io/apps/_/devices) menu item under the "Live Updates" section in the sidebar. Next, select the device you want to delete. In the menu, click on the "Delete" button to delete the device.

Please note that deleting a device will **not lower your Monthly Active Users (MAU) count** as this is based on unique devices that have connected within the current billing period.

# Update Electron Apps

Live Updates work for desktop apps built with the [Capacitor Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/index.md) the same way as on Android and iOS: the Live Update SDK downloads a new web bundle, the platform serves it, and the packaged Electron binary stays untouched. A desktop app uses the **same Capawesome Cloud app and app ID** as your mobile app — no changes in the Console are required.

This page covers what is specific to Electron. For the general setup — creating an app, configuring the SDK, and publishing your first bundle — follow [Get Started](https://capawesome.io/docs/cloud/live-updates/setup/index.md) first.

## Prerequisites

- A **Capacitor 8** app with Live Updates set up as described in [Get Started](https://capawesome.io/docs/cloud/live-updates/setup/index.md). The Capacitor 6 and 7 LTS releases of the SDK do not include the Electron implementation.
- `@capawesome/capacitor-electron` version `0.2.0` or later.
- `@capawesome/capacitor-live-update` version `8.5.0` or later.

## Installation

Add the Electron platform to your project:

```
npm install @capawesome/capacitor-electron
npx cap add @capawesome/capacitor-electron
cd electron && npm install && cd ..
```

Then sync your project. The Electron implementation of the Live Update SDK is registered automatically during the sync, so no additional configuration is required:

```
npx cap sync @capawesome/capacitor-electron
```

Always use the full package name

A bare `npx cap sync` only processes Android, iOS, and web, and `npx cap sync electron` resolves to the unrelated `electron` npm package and silently does nothing. Always pass `@capawesome/capacitor-electron` to Capacitor CLI commands.

For packaging, live reload, and other platform details, see the [Capacitor Electron platform](https://capawesome.io/docs/sdks/capacitor/electron/index.md) documentation.

## Configuration

The SDK reads the `LiveUpdate` section of your Capacitor configuration on Electron as well, so the `appId`, `autoUpdateStrategy`, `readyTimeout`, and all other options from [Get Started](https://capawesome.io/docs/cloud/live-updates/setup/#step-3-configure-the-sdk) apply unchanged.

### App version

On Electron, the app version is the `version` field of `electron/package.json`. The SDK reports it as both `versionCode` and `versionName`, and Capawesome Cloud uses it to decide which bundles are compatible with the installed app. The scaffolded project starts at `0.0.0`.

Bump the version for every desktop release

Version constraints can only distinguish desktop releases if each one has its own `version`. Keep `electron/package.json` in sync with your release process — for example by bumping it together with your mobile version codes.

### Versioned channel

[Versioned channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels) pin each release to its own channel. On Android and iOS, the channel is set natively at build time. On Electron, set it in the `plugins` section of `electron/capacitor.electron.config.ts`. The file is executable TypeScript, so the channel can be derived from the app version:

electron/capacitor.electron.config.ts

```
import { defineConfig } from "@capawesome/capacitor-electron/config";
import packageJson from "./package.json";

export default defineConfig({
  plugins: {
    LiveUpdate: {
      defaultChannel: `production-${packageJson.version}`,
    },
  },
});
```

The `plugins` section is merged over the `plugins` section of your Capacitor configuration **per plugin key, and the Electron configuration wins**: keys you set here override the same keys in `capacitor.config.ts`, while keys you don't mention are kept. Importing `./package.json` requires `resolveJsonModule` in `electron/tsconfig.json`, which the scaffold already enables.

## Publish an update

Publishing works exactly as described in [Publish an Update](https://capawesome.io/docs/cloud/live-updates/publish/index.md). Upload the same web assets you ship to mobile:

```
npm run build
npx @capawesome/cli apps:liveupdates:upload --channel production-1.2.0
```

Electron devices receive the latest `zip` bundle of their channel, subject to the same [rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md), [rollbacks](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md), and [code signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) rules as mobile devices.

### Versioned bundles

If you use [versioned bundles](https://capawesome.io/docs/cloud/live-updates/bundles/#versioned-bundles) instead of versioned channels, restrict a bundle to a range of Electron app versions with the `--electron-min`, `--electron-max`, and `--electron-eq` flags on [`apps:liveupdates:upload`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesupload) and [`apps:liveupdates:register`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesregister):

```
npx @capawesome/cli apps:liveupdates:upload \
  --channel production \
  --electron-min 1.2 \
  --electron-max 1.3.5
```

The value is the Electron app version in the format `major[.minor[.patch]]`, where omitted components count as `0` (`1.2` matches `1.2.0`). Prerelease suffixes are not supported in the flags; a prerelease suffix in the installed app version (for example `1.3.0-beta.1`) is ignored when matching. `--electron-eq` excludes a single exact version, like `--android-eq` and `--ios-eq`.

The Electron flags are independent of the Android and iOS flags: a bundle without Electron constraints is delivered to every Electron version, and `--android-*` and `--ios-*` constraints never affect Electron devices.

## Differences to Android and iOS

- **App version**: Both `versionCode` and `versionName` are the `version` from `electron/package.json`. See [App version](#app-version).
- **Artifact type**: Only `zip` bundles are delivered to Electron devices, so [delta updates](https://capawesome.io/docs/cloud/live-updates/bundle-size/#delta-updates-manifest) are not available.
- **Automatic rollback**: The rollback is kill-safe: if the app is closed or crashes before `ready()`, it happens on the next start.
- **Storage**: Bundles and state live in the `capawesome-live-update` directory inside the app's [`userData`](https://www.electronjs.org/docs/latest/api/app#appgetpathname) directory.
- **Default channel**: Configured in `electron/capacitor.electron.config.ts` instead of `strings.xml` or `Info.plist`. See [Versioned channel](#versioned-channel).
- **Binary updates**: Changes to the `electron/` project, Electron itself, or a plugin's Electron implementation need a new desktop release, for example via [electron-updater](https://www.electron.build/auto-update).

## Troubleshooting

Start with the general [Troubleshooting](https://capawesome.io/docs/cloud/live-updates/troubleshooting/index.md) page. The following issues are specific to Electron:

- **`npx cap sync electron` does nothing**: The command resolves to the `electron` npm package, not the platform. Run `npx cap sync @capawesome/capacitor-electron` instead.
- **Every desktop release reports version `0.0.0`**: The `version` in `electron/package.json` was never changed from the scaffold default. Version constraints and versioned channels can't distinguish your releases, and the reset on a version change never happens. Bump the version for every release.
- **A `manifest` bundle isn't delivered**: Electron devices only receive `zip` bundles. Upload with the default `zip` artifact type.
- **The app runs an old bundle after a desktop update**: This is expected. The SDK resets to the packaged bundle when the app version changes and picks up the next matching bundle on the following check.
- **Reading the SDK logs**: The SDK logs with a `[LiveUpdate]` prefix to the main process output — the terminal that started `npx cap run @capawesome/capacitor-electron`. Renderer output is available in the Chromium DevTools.
- **Resetting the SDK state**: Quit the app and delete the `capawesome-live-update` directory inside the app's `userData` directory. The app then starts with the packaged bundle and a new device ID.

## Next steps

- [Subscribe to a channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md) — choose which channel your desktop app receives updates from.
- [Roll back a release](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md) — recover from a bad update.
- [Automate publishing in CI/CD](https://capawesome.io/docs/cloud/live-updates/integrations/index.md) — upload bundles from your pipeline.

# Estimate Usage

Live Updates are billed by **monthly active users (MAU)** and **data transfer**. Storage is **unlimited** with no usage-based charges ([fair use](/legal/terms-of-service/) applies). This guide helps you estimate both billed metrics so you can pick the right plan and avoid surprises. For the hard limits, see [Limits & quotas](https://capawesome.io/docs/cloud/live-updates/limits/index.md).

## Estimate monthly active users

A device counts as **one MAU** the first time it checks for an update in a given month, regardless of how many times it checks afterward or how many updates it downloads.

```
Expected MAU ≈ number of devices that open your app at least once per month
```

So your MAU is essentially your active install base — update frequency does **not** increase it. A device that opens your app daily counts the same as one that opens it once.

## Estimate data transfer

Data transfer is the bandwidth used to **deliver** bundles to devices. Only downloads count toward your allowance — **uploading** bundles to Capawesome Cloud is free and does not use data transfer.

```
Data transfer ≈ MAU × updates downloaded per device per month × bundle size
```

For example, an app with **1,000 MAU** that publishes **4 updates per month** at **~10 MB** each:

```
1,000 MAU × 4 updates × 10 MB = 40 GB per month
```

This is just an example — your actual data transfer varies with the size of your updates and how many of them each device downloads.

## Reduce your usage

- [Reduce update size](https://capawesome.io/docs/cloud/live-updates/bundle-size/index.md) — smaller bundles (and delta updates that ship only the changed files) mean less data transfer per delivery.
- Publish deliberately — every new bundle a device downloads adds to data transfer, so avoid unnecessary republishes.

# FAQ

## General

### Are Live Updates compliant with app store policies?

Yes. Both Apple and Google explicitly allow downloading and executing interpreted code (such as JavaScript) inside a WebView, as long as it doesn't change the app's primary purpose or bypass platform security. Live Updates only update the web layer, so they stay compliant. See [How Live Updates Work](https://capawesome.io/docs/cloud/live-updates/how-it-works/#are-live-updates-compliant-with-app-store-policies) for the details.

### What changes can I ship as a Live Update?

Only **binary-compatible** changes — anything that lives in your web layer. Changes to native code, plugins, or native configuration require an app store release. See [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md).

### Can I use Live Updates in a desktop app?

Yes. Desktop apps built with the Capacitor Electron platform receive Live Updates from the same Capawesome Cloud app as your mobile app. See [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/index.md). The Capacitor Tauri platform compiles the web assets into the binary, so Live Updates aren't available there.

## Bundles

### How do I restrict bundles to specific native versions?

Use [versioned channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels) or [versioned bundles](https://capawesome.io/docs/cloud/live-updates/bundles/#versioned-bundles).

### How do I roll back to a previous bundle?

See [Roll back a release](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md).

### How do I roll out a bundle to only a subset of users?

See [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md).

### What is the maximum bundle size? How are MAU and data transfer billed?

See [Limits & quotas](https://capawesome.io/docs/cloud/live-updates/limits/index.md) and [Estimate usage](https://capawesome.io/docs/cloud/live-updates/estimate-usage/index.md).

### What happens if I delete a bundle?

It is no longer available for download. Devices that already downloaded it keep using it until they receive a new update. If other bundles exist in the channel, the previous one becomes the latest available bundle.

## Usage & billing

### How is my Monthly Active Users (MAU) count measured?

A device counts as one active user the first time it checks for an update in a given billing month. Additional checks by the same device that month don't add to the count, and [deleting a device](https://capawesome.io/docs/cloud/live-updates/devices/#delete-a-device) doesn't lower it. See [Limits & quotas](https://capawesome.io/docs/cloud/live-updates/limits/#monthly-active-users-mau) for details.

### How is data transfer measured? Is it only bundle downloads?

Data transfer is the bandwidth used to **deliver** bundles to devices — in other words, bundle downloads. Only downloads count toward your allowance; uploading bundles to Capawesome Cloud is free. See [Estimate usage](https://capawesome.io/docs/cloud/live-updates/estimate-usage/#estimate-data-transfer) to predict your consumption.

### What happens if I exceed my plan limits?

Both the MAU and data transfer limits are enforced. When you reach the MAU limit, no new devices can register. When you reach the data transfer limit, bundle deliveries stop. In either case, devices no longer receive Live Updates until you upgrade your plan. Devices keep running the bundle they already downloaded.

### Are there overage charges if I go over my allowance?

No. Allowances are hard limits, not metered overage, so you're never billed automatically for exceeding them. Once a limit is reached, the affected service pauses (see above) until you [upgrade your plan](https://capawesome.io/docs/cloud/organizations/billing/manage/#upgrading-your-plan).

### Can I see usage per app?

Usage is tracked at the organization level. Per-app usage reporting is currently in private beta — [reach out to us](https://capawesome.io/docs/support/index.md) if you'd like access.

## Self-hosting

### Which limits still apply when I self-host bundles?

The MAU limit still applies, because devices continue to check for updates through Capawesome Cloud. The data transfer limit does **not** apply — devices download bundles directly from your own server, so that bandwidth isn't measured by Capawesome. See [Self-host bundles](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md).

### Is data transfer still measured if I host bundles in my own environment?

No. With self-hosting, bundles are served from your infrastructure (for example, your own AWS environment), so their download traffic never touches Capawesome Cloud and isn't counted. You can serve as many updates as you like.

### Are analytics, metadata, and administration still handled by Capawesome Cloud?

Yes. Only the bundle files move to your server. The update-metadata check, device and channel management, and everything in the Console remain hosted by Capawesome Cloud.

### Are there functional differences between cloud-hosted and self-hosted bundles?

The workflow is the same, with one current exception: [delta updates](https://capawesome.io/docs/cloud/live-updates/bundle-size/#delta-updates-manifest) aren't supported when self-hosting, so bundles are delivered as full `zip` artifacts. Everything else — channels, rollouts, rollbacks, and code signing — works the same way.

## Channels

### What happens if I delete a channel?

All bundles associated with the channel are deleted as well. Devices that already downloaded a bundle keep using it until they receive a new update.

## Devices

### What happens if I delete a device?

It is removed from the device list. The next time the device checks for an update, it is restored. Deleting a device does **not** affect your Monthly Active Users (MAU) count.

## Privacy

### Is any Personally Identifiable Information (PII) collected?

No. Only a device-generated identifier is sent to Capawesome Cloud, used to count Monthly Active Users (MAU). The identifier is only valid while the app is installed.

# How Live Updates Work

A hybrid app has two layers. The **native layer** is the compiled binary installed from the App Store or Google Play — it contains the WebView, the native plugins, and the platform glue. The **web layer** is everything that runs inside that WebView: your HTML, CSS, JavaScript, and static assets.

A Live Update is an **over-the-air (OTA) update of the web layer only**. The native binary stays untouched. Instead of pushing a new build to the stores, you upload a new web bundle to Capawesome Cloud, and the Live Update SDK in your app downloads it, swaps it in, and reloads.

That constraint is also the feature: because nothing native changes, you don't need an app store review and your users don't have to take any action. It also means a bundle must stay compatible with the installed binary — see [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md).

## Key terms

Live Updates revolve around a handful of entities in Capawesome Cloud. Here's what each one means:

- **App** — the top-level container in Capawesome Cloud that everything below belongs to. It maps to a single Capacitor or Cordova app.
- **Build** — a build of your app's web assets, run in the cloud or uploaded from your machine. Each build produces one artifact.
- **Artifact** — the output of a build. For a web build, that artifact *is* the bundle: a zip of your web assets, or a manifest pointing to your own server for [self-hosted](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) bundles.
- **Bundle** — the artifact of a web build (the bundle's ID is that build artifact's ID): the packaged web assets delivered over-the-air. It's the unit you deploy to a channel — one "Live Update". See [Bundles](https://capawesome.io/docs/cloud/live-updates/bundles/index.md).
- **Channel** — a named stream of bundles that devices subscribe to, such as `production` or `staging`. Each device subscribes to exactly one channel. See [Channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md).
- **Deployment** — the link between a bundle and a channel. Deploying a bundle to a channel makes it the latest update for that channel's devices.
- **Rollout** — a deployment delivered gradually, to a growing percentage of the channel's devices, so you can limit exposure to a bad release. See [Rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md).
- **Device** — an installed instance of your app. Each device receives the latest [compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) bundle from its channel. See [Devices](https://capawesome.io/docs/cloud/live-updates/devices/index.md).

The publishing side fits together like this — a build produces an artifact, that artifact is the bundle, and a deployment puts it on a channel:

How channels, deployments, builds, and artifacts relate in Capawesome Cloud

On the device side, each device subscribes to one channel and pulls the latest bundle deployed there. The next section follows a single update all the way from your machine to that device.

## The update lifecycle

Every Live Update follows the same path, from publishing a bundle to applying it on a device. It happens in two stages.

**On your side** — you publish the update:

1. **Build** — produce your web assets, locally or in the cloud. See [Publish an update](https://capawesome.io/docs/cloud/live-updates/publish/index.md).
1. **Deploy** — deploy the resulting bundle to a [channel](https://capawesome.io/docs/cloud/live-updates/channels/index.md), making it the latest update for that channel's devices.

**On the device** — the [Live Update SDK](https://capawesome.io/docs/cloud/live-updates/setup/index.md) takes over automatically:

1. **Check** — the SDK asks Capawesome Cloud whether a newer bundle is available for the device's channel.
1. **Download** — if there is, the bundle is downloaded and written to a local directory inside the app's sandbox.
1. **Stage** — the SDK records the downloaded bundle as the *next* bundle to load.
1. **Apply** — on the next app launch (or immediately, if you call `reload()`), the WebView loads the new bundle instead of the one shipped inside the binary.

By default, the WebView loads your web assets from a local path bundled inside the native app — the output of your build at the time you shipped the binary. Applying a Live Update simply points the WebView at the downloaded bundle's path instead. The path is persisted natively (in `SharedPreferences` on Android, `UserDefaults` on iOS, and the app's `userData` directory on [Electron](https://capawesome.io/docs/cloud/live-updates/electron/index.md)), so the app keeps using the updated bundle across restarts until a newer one is applied.

When and how the *Apply* step happens is controlled by your [update strategy](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md).

## Are Live Updates compliant with app store policies?

Yes. Both Apple and Google explicitly allow downloading and executing code inside a WebView, which is exactly what Live Updates do.

- **Apple** — the App Store Review Guidelines (section 3.3.2) allow downloading interpreted code as long as it doesn't change the primary purpose of the app, doesn't create a store for other code, and doesn't bypass the system's signing or sandbox. Web code running in a `WKWebView` meets all three conditions.
- **Google Play** — the Device and Network Abuse policy forbids apps from modifying or replacing themselves outside of Play, with an explicit exception for code interpreted in a runtime such as JavaScript in a WebView.

In short, app stores draw the line at *native* self-modification. Live Updates only touch the web layer, so they stay safely on the right side of that line.

# Limits & Quotas

This page summarizes the limits that apply to Live Updates. Plan-specific allowances (such as included MAU and data transfer) are listed on the [pricing page](https://capawesome.io/pricing/).

## Bundle size

A single bundle can be up to **1 GB**. In practice you should aim for much smaller bundles — see [Reduce update size](https://capawesome.io/docs/cloud/live-updates/bundle-size/index.md) for how to keep them lean.

## Monthly active users (MAU)

Live Updates are billed by **monthly active users**. A device counts as active in a given month the first time it checks for an update that month. Your plan includes a number of MAU. When you reach it, no new devices can register until you upgrade your plan — there are no metered overage charges. To estimate your expected usage, see [Estimate usage](https://capawesome.io/docs/cloud/live-updates/estimate-usage/index.md).

## Data transfer

Live Updates are also billed by **data transfer** — the bandwidth used to deliver bundles to devices. Only **deliveries** (downloads) count toward your allowance; **uploading** bundles to Capawesome Cloud is free. Your plan includes a data transfer allowance. When you reach it, bundle deliveries stop until you upgrade your plan — there are no metered overage charges. To estimate your expected usage, see [Estimate usage](https://capawesome.io/docs/cloud/live-updates/estimate-usage/index.md).

## Storage

Storage is **unlimited**, with no usage-based charges for publishing and retaining bundles. [Fair use](/legal/terms-of-service/) applies.

## Related

- [Estimate usage](https://capawesome.io/docs/cloud/live-updates/estimate-usage/index.md) — predict MAU and data transfer against your plan.
- [Reduce update size](https://capawesome.io/docs/cloud/live-updates/bundle-size/index.md) — keep bundles small to lower data transfer.
- [Pricing](https://capawesome.io/pricing/) — plan-specific allowances.

# Logs

Logs are a powerful tool for debugging your app. They provide detailed information on each incoming request and outgoing response from devices, including the status code and body.

## View logs

To view logs using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to view logs for, and click on the [Logs](https://console.cloud.capawesome.io/apps/_/logs) menu item under the "Live Updates" section in the sidebar.

You can filter logs by ID and device ID.

The following properties are available in the logs:

- **ID**: The ID of the log entry.
- **Device ID**: The ID of the device that made the request.
- **Request URL**: The URL of the request. This URL contains various parameters, including the app ID, channel name, and device ID. Use this URL to check if the correct parameters are being sent to the Capawesome Cloud.
- **Response body**: The body of the response. This body contains the bundle ID and the URL of the bundle or the error message if the request failed.
- **Response status**: The status code and text of the response. This status code indicates whether the request was successful or not. A status code of 200 indicates success, while any other status code indicates an error.
- **Created at**: The date and time when the request was made. This date and time is in UTC format.

# Download and Apply Updates

For full control over the update process, the Live Update SDK exposes the individual steps of the update lifecycle:

1. **`fetchLatestBundle()`** — check for updates without downloading them.
1. **`downloadBundle()`** — download a bundle without applying it.
1. **`setNextBundle()`** — set a bundle as the one to apply on the next launch.
1. **`reload()`** — apply the new bundle immediately.

Disable automatic updates

When handling updates manually, set `autoUpdateStrategy` to `none` (or leave it unset) to prevent conflicts with the automatic update mechanism. See [Choose an update strategy](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md).

## Check for updates

Check for a new bundle without downloading it:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const result = await LiveUpdate.fetchLatestBundle({ channel: "production" });
if (result.bundleId) {
  console.log("New update available: " + result.downloadUrl);
}
```

```
const result = await cordova.plugins.LiveUpdate.fetchLatestBundle({ channel: "production" });
if (result.bundleId) {
  console.log("New update available: " + result.downloadUrl);
}
```

This returns information about the latest bundle, including its ID and download URL. Pass the `channel` to check a specific channel — see [Subscribe to a Channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md) for the available options.

## Download an update

Download a bundle — the SDK extracts the files and moves them into place:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.downloadBundle({ bundleId, url });
```

```
await cordova.plugins.LiveUpdate.downloadBundle({ bundleId, url });
```

## Apply an update

Stage a downloaded bundle as the next one to load:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.setNextBundle({ bundleId });
```

```
await cordova.plugins.LiveUpdate.setNextBundle({ bundleId });
```

To apply it immediately instead of on the next launch, call `reload()`:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.reload();
```

```
await cordova.plugins.LiveUpdate.reload();
```

# Privacy & Data Residency

The privacy of your users is our first priority, and Capawesome Cloud can be used in a fully GDPR-compliant way. Read on for [what data is collected](#data-collection) and how to choose the [server location](#data-residency).

## Data Collection

Capawesome Cloud only collects the data necessary to provide Live Updates:

- **App ID** — associates the app with the correct account.
- **App Version Code / Name** — determines which updates are compatible with the app.
- **Platform** — Android, iOS, or Electron, to determine compatible updates.
- **Device ID** — a random identifier created on first launch, used to deliver updates to a device and to count Monthly Active Users (MAU).
- **Bundle ID** — the [bundle](https://capawesome.io/docs/cloud/live-updates/bundles/index.md) currently installed on the device.
- **Channel Name** — the [channel](https://capawesome.io/docs/cloud/live-updates/channels/index.md) the device receives updates from.
- **OS Version** — to determine compatible updates.
- **SDK Version** — the version of the Live Update SDK.

No personal data is collected — only the information required to deliver Live Updates. The SDK is open source, so you can verify exactly what is sent.

## Data Residency

As a European company, Capawesome Cloud offers an EU-based-and-hosted option so that not even connection information such as IP addresses leaves the European Union. To use the European cloud, set the `serverDomain` option to `api.cloud.capawesome.eu`:

capacitor.config.json

```
{
  "plugins": {
    "LiveUpdate": {
      "serverDomain": "api.cloud.capawesome.eu"
    }
  }
}
```

config.xml

```
<preference name="SERVER_DOMAIN" value="api.cloud.capawesome.eu" />
```

If you don't set `serverDomain`, the default `api.cloud.capawesome.io` is used, which utilizes servers around the world. You can find more in our [Privacy Policy](/legal/privacy-policy/).

# Publish a Live Update

Publishing an update is the workflow you repeat every release: get your web assets into Capawesome Cloud as a new **bundle**, which is then delivered to devices according to your [update strategy](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md).

There are two ways to do it:

- **[Upload from your machine](#upload-from-your-machine)** — build your web assets locally and upload the result. Works on any Live Updates plan and doesn't use build minutes.
- **[Build in the cloud](#build-in-the-cloud)** — let Capawesome Cloud build your web assets for you, for a consistent, reproducible release.

## Upload from your machine

Build your web assets, then upload them with the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) — the same command for Capacitor and Cordova:

```
npm run build
npx @capawesome/cli apps:liveupdates:upload
```

You'll be prompted for the path to your web assets directory (e.g. `www` or `dist`) and the target app. After the upload completes, the bundle is available to your users. Open the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page in the Console to review it.

To run it non-interactively (for example in a script), pass the values as flags:

```
npx @capawesome/cli apps:liveupdates:upload \
  --app-id 00000000-0000-0000-0000-000000000000 \
  --path dist \
  --channel production
```

### Options

| Option                 | Description                                                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--channel`            | The channel to publish to. Defaults to the channel's default.                                                                        |
| `--private-key`        | Sign the bundle with your private key. See [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md). |
| `--rollout-percentage` | Release to a subset of devices first. See [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md).     |
| `--artifact-type`      | `zip` (default) or `manifest`. See [Reduce update size](https://capawesome.io/docs/cloud/live-updates/bundle-size/index.md).         |
| `--git-ref`            | Associate the bundle with a Git commit.                                                                                              |

See the [CLI command reference](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesupload) for the full list.

## Build in the cloud

Instead of building locally, you can let Capawesome Cloud build your web assets and deploy the result — all in a single command:

```
npx @capawesome/cli apps:builds:create --platform web --git-ref main --channel production
```

Capawesome Cloud checks out the given Git reference, installs your dependencies, builds your web assets, and deploys the resulting bundle to the channel.

Why build in the cloud:

- **Consistent, reproducible builds.** Every release uses the same Node.js version, the same dependencies, and the same configuration — no more "works on my machine" surprises between team members or CI runners.
- **Your environment and secrets.** Cloud builds can use the [environment variables and secrets](https://capawesome.io/docs/cloud/native-builds/environments/index.md) you've configured in Capawesome Cloud (pass `--environment`). A local upload can't access those.
- **Builds from Git, not your working tree.** Build from a branch, tag, or commit so what ships always matches what's in your repository.
- **No local tooling required.** Useful in CI, or simply to keep your machine out of the release path.

Building in the cloud uses **build minutes**, so it's available on plans that include build runners. If your plan doesn't, the [upload](#upload-from-your-machine) approach works on any Live Updates plan.

For the full set of build options and ready-made pipeline examples, see [Native Builds](https://capawesome.io/docs/cloud/native-builds/builds/index.md) and [Integrations](https://capawesome.io/docs/cloud/live-updates/integrations/index.md).

## Choose a channel

Every device receives updates from a [channel](https://capawesome.io/docs/cloud/live-updates/channels/index.md). If you don't specify one, the bundle is published to the default channel. Pass `--channel` (with either approach above) to target a specific channel — for example a `staging` channel for testers, or a versioned `production-<version>` channel to keep updates [compatible with the installed app version](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md):

```
npx @capawesome/cli apps:liveupdates:upload --channel staging
```

## Next steps

- [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md) — release to a percentage of users first.
- [Roll back a release](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md) — recover from a bad update.
- [Automate publishing in CI/CD](https://capawesome.io/docs/cloud/live-updates/integrations/index.md).

# Proxy API Requests

By default, the Live Update SDK talks to the Capawesome Cloud API directly. If you'd rather keep that traffic on infrastructure you control, you can put a reverse proxy in front of the API and point the SDK at your own domain instead. The proxy forwards every request to Capawesome Cloud and returns the response, so updates keep working exactly as before.

## Why proxy requests?

Running your own proxy is optional, but it gives you a few things:

- **Own domain**: Serve the API under a hostname you control instead of `api.cloud.capawesome.io`.
- **Observability**: Log, inspect, and monitor update traffic before it leaves your network.
- **Network control**: Apply your own firewall, WAF, or access rules to the traffic.
- **IP anonymization**: Strip client IP addresses before they reach Capawesome Cloud (Enterprise plan only — see [IP anonymization](#ip-anonymization)).

## How it works

The Live Update SDK sends all of its requests to a single host. Once you point it at your proxy, the flow looks like this:

1. The app sends update requests to your domain (for example, `api.example.com`).
1. Your reverse proxy forwards each request to `https://api.cloud.capawesome.io`.
1. Capawesome Cloud responds, and your proxy passes the response back to the app.

## Requirements

You can build the proxy with any technology — nginx, Caddy, a cloud load balancer, an edge function, whatever fits your stack. Whichever you choose, it must:

- **Terminate HTTPS**: Serve your domain over HTTPS so the SDK can connect securely.
- **Forward to the API**: Proxy every request to `https://api.cloud.capawesome.io` and send `api.cloud.capawesome.io` as the `Host` header.
- **Forward the client IP**: Set the `X-Real-IP` header to the original client's IP address.

The last point matters more than it looks:

Forward the client IP

Capawesome Cloud applies rate limits per client IP based on the `X-Real-IP` header. If your proxy doesn't forward it, every request appears to come from the proxy itself, and all of your users share a single rate limit. Always set `X-Real-IP` to the real client IP — unless you're on the Enterprise plan and have set up [IP anonymization](#ip-anonymization).

## Reference implementation

To get you started, we maintain an open-source [Cloud API Proxy](https://github.com/capawesome-team/docker-cloud-api-proxy) repository. It's a minimal nginx-based Docker image — a `Dockerfile` and an nginx config — that forwards everything to the Capawesome Cloud API with the required headers already in place.

The relevant part of the nginx configuration looks like this:

default.conf

```
server {
    listen 80;

    server_name api.example.com;

    location / {
        proxy_pass https://api.cloud.capawesome.io;
        proxy_ssl_server_name on;

        proxy_set_header Host "api.cloud.capawesome.io";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Replace `api.example.com` with your own domain and terminate TLS in front of the container in production (for example, via a load balancer or a reverse proxy such as Caddy or Traefik). This image is only a reference — you're free to implement the proxy with any tooling you prefer, as long as it meets the [requirements](#requirements) above.

## Configure the SDK

Once your proxy is reachable over HTTPS, point the SDK at it by setting the `serverDomain` option to your domain:

capacitor.config.json

```
{
  "plugins": {
    "LiveUpdate": {
      "serverDomain": "api.example.com"
    }
  }
}
```

config.xml

```
<preference name="SERVER_DOMAIN" value="api.example.com" />
```

The `serverDomain` option takes a bare domain — no scheme and no path. The SDK always connects over HTTPS, so make sure your proxy is served over HTTPS as well.

## IP anonymization

Some teams don't want client IP addresses leaving their own infrastructure at all. On the **Enterprise** plan, you may drop the `X-Real-IP` header in your proxy so that no client IP reaches Capawesome Cloud. Because every request then arrives from your proxy's IP, we configure a dedicated, higher rate limit for that IP so your users aren't throttled as a single client.

[Contact our sales team](/contact-sales/) to enable IP anonymization for your proxy.

## Next steps

- [Self-Host Bundles](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) — keep your bundles on your own server while Capawesome Cloud handles update checks.
- [Privacy & Data Residency](https://capawesome.io/docs/cloud/live-updates/privacy/index.md) — see what data is collected and how to choose an EU-based server location.
- [Get Started](https://capawesome.io/docs/cloud/live-updates/setup/index.md) — install and configure the Live Update SDK.

# Roll Back a Release

A rollback reverts to a working bundle when a new one doesn't work as expected. The SDK supports **automatic** rollbacks (self-healing), and you can also roll back **manually** from the CLI or Console.

## Automatic Rollbacks

The SDK can automatically roll back to the built-in bundle shipped with the installed native app version if a new bundle fails to start. Since that bundle is guaranteed to run on the current binary, it's always a safe fallback. Configure `readyTimeout` and `autoBlockRolledBackBundles`:

capacitor.config.json

```
{
  "plugins": {
    "LiveUpdate": {
      "autoBlockRolledBackBundles": true,
      "readyTimeout": 10000
    }
  }
}
```

config.xml

```
<preference name="AUTO_BLOCK_ROLLED_BACK_BUNDLES" value="true" />
<preference name="READY_TIMEOUT" value="10000" />
```

`readyTimeout` is the deadline (in milliseconds): if your app doesn't call `ready()` within this window of starting, the SDK assumes the bundle is broken and reverts on the next launch. `autoBlockRolledBackBundles` prevents a rollback loop by blocking a bundle that has already triggered a rollback.

For this to work, call `ready()` as early as possible at app start — as soon as your bootstrap code has run without crashing:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.ready();
```

```
document.addEventListener("deviceready", async () => {
  await cordova.plugins.LiveUpdate.ready();
});
```

## Manual Rollbacks

Roll back to a previous bundle from the CLI or Console.

Use the [`apps:liveupdates:rollback`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesrollback) command:

```
npx @capawesome/cli apps:liveupdates:rollback
```

Select the app and channel, then choose the deployment you want to roll back to.

In the [Console](https://console.cloud.capawesome.io/), open the channel's history page, find the deployment you want to roll back to, and click **Rollback**. A new deployment is created that points to the selected bundle.

## Next steps

- [Security](https://capawesome.io/docs/cloud/live-updates/security/index.md) — code signing, protected channels, and token handling for production apps.
- [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md) — limit how many users get a new bundle before it reaches everyone.

# Roll Out Gradually

Rollouts let you release a Live Update to a small percentage of users first and then increase the rollout over time. This limits exposure to potential issues. Rollouts are managed entirely from the CLI or Console, so they work the same for Capacitor and Cordova.

## Manage Rollouts

You can manage rollouts associated with your app using the Capawesome CLI or the Capawesome Cloud Console.

### Start a Rollout

Rollouts can be started when deploying a build to a live update channel.

To start a rollout using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:liveupdates:upload`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesupload) command with the `--rollout-percentage` flag:

```
npx @capawesome/cli apps:liveupdates:upload --channel production --rollout-percentage 10
```

You will be prompted to select the app you want to upload the bundle for and to provide the path to the bundle file. The CLI will then upload and deploy the bundle to the specified channel in the Capawesome Cloud, starting a rollout to the specified percentage of users.

To start a rollout using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to start the rollout for, and click on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) menu item in the sidebar. Next, click on the "Create deployment" button, select the build to deploy, choose the live update channel, click on "Advanced", and set the "Rollout (%)" to the desired initial percentage of users to receive the update.

Click on the "Create" button to complete the deployment and start the rollout.

### Update Rollout Percentage

Update the rollout percentage to increase or decrease the number of users receiving the update.

To update the rollout percentage using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:liveupdates:rollout`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesrollout) command:

```
npx @capawesome/cli apps:liveupdates:rollout --channel production --percentage 50
```

You will be prompted to select the app you want to update the rollout for and to provide the channel name and the new rollout percentage. The CLI will then update the rollout percentage for the latest deployment in this channel in the Capawesome Cloud.

To update the rollout percentage using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to update the rollout for, and click on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) menu item in the sidebar. Next, click on the deployment you want to update the rollout for, click on the "Settings" tab, and update the rollout percentage to the desired percentage of users to receive the update.

Click on the "Save" button to complete the update of the rollout percentage.

### Complete a Rollout

Complete a rollout to make the update available to all users.

To complete a rollout using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:liveupdates:rollout`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesrollout) command with a percentage of `100`:

```
npx @capawesome/cli apps:liveupdates:rollout --channel production --percentage 100
```

You will be prompted to select the app you want to complete the rollout for and to provide the channel name. The CLI will then complete the rollout for the latest deployment in this channel in the Capawesome Cloud.

To complete a rollout using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), navigate to the app you want to complete the rollout for, and click on the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) menu item in the sidebar. Next, click on the deployment you want to complete the rollout for, click on the "Settings" tab, and set the rollout percentage to 100 to make the update available to all users.

Click on the "Save" button to complete the rollout.

## Advanced

### Multi-Channel Rollouts

You can implement multi-channel rollouts by using separate channels for the rollout and stable releases. For example, you can first check for an update in a "production-rollout" channel and, if no update is available, check in the "production" channel for the stable release. This way, users in the rollout phase receive updates from the "production-rollout" channel, while all other users receive updates from the stable "production" channel. The deployment in the "production-rollout" channel can be gradually increased until it reaches 100%, at which point you can deploy the same bundle to the "production" channel for all users. The rollout percentage in the "production" channel should always be set to 100% to ensure all other users receive the stable update.

Disable Automatic Updates

If you are manually handling the update process, it is **strongly recommended** to set the `autoUpdateStrategy` configuration option to `none` to prevent conflicts with the automatic update mechanism.

The following example checks the rollout channel first and falls back to the stable channel:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const rollout = await LiveUpdate.sync({ channel: "production-rollout" });
if (rollout.nextBundleId) return;
await LiveUpdate.sync({ channel: "production" });
```

```
const rollout = await cordova.plugins.LiveUpdate.sync({ channel: "production-rollout" });
if (rollout.nextBundleId) return;
await cordova.plugins.LiveUpdate.sync({ channel: "production" });
```

If a device is part of the rollout, it will always receive the update from the "production-rollout" channel first until a new deployment is made to that channel. This ensures that devices do not get stuck in an update loop. Once the rollout is complete, you can deploy the same bundle to the "production" channel for all users. The [Live Update SDK](https://capawesome.io/docs/cloud/live-updates/setup/index.md) will recognize that the device is already on the latest bundle and will not attempt to re-download it. You can then remove the "production-rollout" channel or keep it for the next rollout.

## Limitations

### Rollout Percentage Calculation

Rollout percentages are calculated based on the **total number of devices in a channel**, not just those compatible with the deployed bundle. When using [versioned bundles](https://capawesome.io/docs/cloud/live-updates/bundles/#versioned-bundles), this means the actual rollout may reach fewer devices than the specified percentage if some devices are incompatible with the update. To ensure more accurate rollouts, use [versioned channels](https://capawesome.io/docs/cloud/live-updates/channels/#versioned-channels) so that only compatible devices are included in the rollout calculation.

# Security

A Live Update replaces the web code running inside your app, so the update path deserves the same care as your release pipeline. This page collects the practices we recommend for production apps. For account-level practices — API tokens, roles, two-factor authentication, and audit logs — see [Cloud security](https://capawesome.io/docs/cloud/security/index.md).

## Sign your bundles

[Code signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) is the most effective control. Your app verifies an RSA signature before it applies a bundle, so anything that wasn't produced by you — or that was modified after upload — is rejected, even if an attacker managed to serve it.

Where you sign decides who holds the private key:

- **Sign locally or in your own CI.** You pass `--private-key` when uploading a bundle, so the key never leaves your machine or your CI secret store, and Capawesome Cloud only ever receives an already signed bundle. This is the strongest setup: nobody at Capawesome can sign a bundle in your name.
- **Sign in Capawesome Cloud.** If Capawesome Cloud builds your web bundle for you, it also signs the bundle, which means you upload your private key as a [web signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/web/index.md). Your key then lives outside your own infrastructure and is used on your behalf. That's the trade-off for letting us build your web bundle, and it's one to make deliberately: if your threat model requires that only you can ever sign a bundle, build and sign the web bundle in your own pipeline and use Capawesome Cloud for your Android and iOS builds.

Either way, never commit the private key to version control, and keep a backup — losing it means shipping a new native version with a new public key.

## Protect your production channels

A [protected channel](https://capawesome.io/docs/cloud/live-updates/channels/#protected-channels) only distributes signed bundles. Mark your production channel as protected so an unsigned bundle can't reach users because someone forgot a flag in a pipeline.

## Enable automatic rollbacks

A bad bundle can take your app down for everyone on the channel until you ship a fix. The SDK can recover on its own. Set `readyTimeout` and `autoBlockRolledBackBundles`, and call `ready()` as early in your bootstrap as possible. If `ready()` doesn't run in time, the SDK falls back on the next launch to the bundle shipped with the installed binary, which is known to run on that binary. See [Automatic rollbacks](https://capawesome.io/docs/cloud/live-updates/rollbacks/#automatic-rollbacks) for the configuration.

Without it, your only path back is a [manual rollback](https://capawesome.io/docs/cloud/live-updates/rollbacks/#manual-rollbacks), and users whose app no longer starts may never check for another update.

## Never ship sensitive data in a bundle

A bundle is client code. It is delivered to every device on the channel, and anyone with the app can extract and read it — obfuscation doesn't change that. Keep out of it:

- **API keys and secrets** for services that charge money or grant write access. Call those services from your backend instead.
- **Credentials of any kind**, including database connection strings, private certificates, and signing keys.
- **Personal data** in fixtures, seed files, or test data. Use anonymized values.
- **Internal endpoints and debug tooling** you don't want exposed, such as admin URLs or verbose logging left enabled.

Treat a bundle exactly like a public web build, because that's what it is. If something must stay private, it belongs on your server behind an authenticated endpoint.

## Next steps

- [Cloud security](https://capawesome.io/docs/cloud/security/index.md) — protect your API tokens and limit who can publish.
- [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) — set up an RSA key pair and verify signatures in your app.
- [Self-host bundles](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) — keep your web artifacts on your own infrastructure.
- [Privacy & data residency](https://capawesome.io/docs/cloud/live-updates/privacy/index.md) — what data Live Updates collect and how to stay on EU servers.

# Self-Host Bundles

For customers with strict security requirements, Capawesome Cloud lets you self-host Live Update bundles. You host the bundles on your own server, and only the metadata required to check for updates is sent to Capawesome Cloud. This has several advantages:

- **Security**: You don't have to share your web artifacts with us and can keep them on your own servers.
- **Data transfer**: You are not affected by our data transfer limits. You can serve as many updates as you want.

## Requirements

To self-host Live Updates, you need to meet the following requirements:

- **Server**: You need to have a high-availability server that can serve static files and handle low to medium levels of traffic (varies based on number of app users).
- **HTTPS**: Your server must support HTTPS. This is required to ensure secure communication between the client and your server.

In addition, we recommend the following:

- **CDN**: Use a Content Delivery Network (CDN) to serve the updates. This can help reduce latency and improve download speeds for users around the world.

## Restrictions

There is one restriction right now:

- **Delta Updates**: Delta updates are not yet supported when self-hosting. This means the artifact type must be `zip` (default). [Reach out to us](mailto:support@capawesome.io) if you need support for delta updates.

## How it works

Flow diagram of self-hosted Live Updates

The process of self-hosting Live Updates is similar to the regular process, with the difference that the bundle is hosted on your server. Here's how it works:

1. **Request metadata**: The client sends a request to Capawesome Cloud to check for updates.

1. **Receive metadata**: If an update is available, Capawesome Cloud responds with the metadata required to download the update. This can look like this:

   ```
   {
       "artifactType": "zip",
       "bundleId": "1e42e1df-f4b3-4564-90d0-2303ca8fbd49",
       "url": "https://server.tld/downloads/1e42e1df-f4b3-4564-90d0-2303ca8fbd49.zip",
   }
   ```

1. **Request file(s)**: The client requests the bundle from your server.

1. **Receive file(s)**: Your server responds with the bundle.

After that, the client can install the update as usual.

## Create a new bundle

To create a new self-hosted bundle on Capawesome Cloud, you can use the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md). First, make sure you have the latest version of the CLI installed:

```
npm install -g @capawesome/cli@latest
```

After that, log in to your account:

```
npx @capawesome/cli login
```

Then, create a new bundle with the [`apps:liveupdates:register`](https://capawesome.io/docs/cloud/cli/commands/#appsliveupdatesregister) command:

```
npx @capawesome/cli apps:liveupdates:register --url https://domain.tld/bundle.zip
```

Replace `https://domain.tld/bundle.zip` with the URL of the bundle on your server. The bundle will be created and immediately available to all users.

## Bonus: Code Signing

To help ensure secure end-to-end delivery, you can sign your updates with a private key. This way, the client can verify that the updates are coming from you and not a malicious actor. To sign your updates, you need to provide a private key and a local path to the artifact when creating the bundle:

```
npx @capawesome/cli apps:liveupdates:register --url https://domain.tld/bundle.zip --private-key ./key.pem --path ./bundle.zip
```

We recommend integrating code signing into your CI/CD pipeline to automate the process. This way you can create a signed bundle directly after uploading the artifact to your server. Check out our [Code Signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) guide for more information on how to sign your updates.

Note

Code signing for self-hosted bundles requires Live Update plugin **6.9.0+** (Capacitor 6), **7.5.0+** (Capacitor 7), **8.0.0+** (Capacitor 8), or **0.1.0+** (Cordova).

# Getting Started

In this guide, you will set up Capawesome Cloud Live Updates in your app and ship your first over-the-air update. The Live Update SDK is available for both **Capacitor** and **Cordova** with full API parity — use the runtime tabs throughout this guide to follow along with your framework.

Prefer to learn from a working example?

Clone a ready-to-run demo app with Live Updates already wired up:

- [Capacitor Live Update demo](https://github.com/capawesome-team/capacitor-live-update-demo)
- [Cordova Live Update demo](https://github.com/capawesome-team/cordova-live-update-demo)

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
- A Capacitor or Cordova app project on your local machine.
- The latest version of the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) installed and [authenticated](https://capawesome.io/docs/cloud/cli/authentication/index.md).

## AI-Assisted Setup (Recommended)

The fastest way to get started is with an AI coding assistant. First, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project:

```
npx skills add capawesome-team/skills --skill capawesome-cloud
```

Then use the following prompt in your preferred AI tool (e.g. [Claude Code](https://www.anthropic.com/claude-code), [Cursor](https://www.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot)):

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up Live Updates in my project.
```

The assistant will create an app in Capawesome Cloud, install and configure the SDK, publish your first update, and verify that everything works. Once complete, continue with [Next Steps](#next-steps).

## Manual Setup

If you prefer to set things up manually, follow the steps below.

### Step 1: Create an App

To identify your app to Capawesome Cloud, first create an app. If you already have one, **skip to Step 2**.

Use the [`apps:create`](https://capawesome.io/docs/cloud/cli/commands/#appscreate) command:

```
npx @capawesome/cli apps:create
```

You will be prompted to select an organization and provide a name. The CLI then creates the app and prints the app ID.

Open the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/apps), select your organization, and click **Create app**. Provide a name and click **Create**.

Copy the app ID — you will need it in the next step.

### Step 2: Install the SDK

Install the Live Update SDK in your project.

```
npm install @capawesome/capacitor-live-update
npx cap sync
```

Older Capacitor versions

For **Capacitor 7**, use `@capawesome/capacitor-live-update@v7-lts`. For **Capacitor 6**, use `@capawesome/capacitor-live-update@v6-lts`.

Electron desktop apps

Shipping a desktop build with the Capacitor Electron platform? Electron support requires **Capacitor 8** and `@capawesome/capacitor-live-update` 8.5.0 or later (not the LTS releases above). Sync it with `npx cap sync @capawesome/capacitor-electron` and see [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/index.md) for the desktop-specific setup.

```
cordova plugin add @capawesome/cordova-live-update --variable APP_ID=00000000-0000-0000-0000-000000000000
```

Replace the `APP_ID` value with the app ID from Step 1.

WebView scheme

The plugin requires the default custom WebView scheme. It does not work if your app sets `Scheme=file` or `AndroidInsecureFileModeEnabled=true`.

### Step 3: Configure the SDK

Configure the SDK with your app ID and the recommended settings. The `autoUpdateStrategy: background` option checks for updates on app start and resume, downloads them in the background, and applies them on the next launch — no extra code required. The `readyTimeout` and `autoBlockRolledBackBundles` options enable [automatic rollback](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md) of a broken update.

capacitor.config.ts

```
import { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: "00000000-0000-0000-0000-000000000000",
      autoUpdateStrategy: "background",
      autoBlockRolledBackBundles: true,
      readyTimeout: 10000
    }
  }
};

export default config;
```

Apply the configuration:

```
npx cap sync
```

Configure the plugin via preferences in your `config.xml`:

config.xml

```
<preference name="APP_ID" value="00000000-0000-0000-0000-000000000000" />
<preference name="AUTO_UPDATE_STRATEGY" value="background" />
<preference name="AUTO_BLOCK_ROLLED_BACK_BUNDLES" value="true" />
<preference name="READY_TIMEOUT" value="10000" />
```

Cordova only reads these preferences when a platform is added, so changes to them don't take effect until you remove and re-add the affected platforms:

```
cordova platform rm android ios
cordova platform add android ios
```

For automatic rollback to work, call `ready()` as early as possible at app start to signal that the new bundle started successfully:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

await LiveUpdate.ready();
```

```
document.addEventListener("deviceready", async () => {
  await cordova.plugins.LiveUpdate.ready();
});
```

### Step 4: Publish Your First Update

Build your web assets, then upload them as a Live Update bundle with the CLI (the same command for both runtimes):

```
npm run build
npx @capawesome/cli apps:liveupdates:upload
```

You will be prompted for the path to your web assets directory (e.g. `www` or `dist`) and the target app. After the upload completes, the bundle is available to your users. Open the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments) page in the Console to see the details.

### Step 5: Test Your Setup

Make a small visible change to your web assets, rebuild, and upload a new bundle with the same command. Then force-close and restart your app.

Force an update check

With an `autoUpdateStrategy`, updates are only checked on resume if the last check was more than 15 minutes ago. During development, **force-close and restart the app** to trigger a check immediately.

Wait around 15–30 seconds, then restart again to see the change take effect. 🎉

Not seeing the update? Head over to [Troubleshooting](https://capawesome.io/docs/cloud/live-updates/troubleshooting/index.md) — it walks through the most common reasons an update doesn't reach the device and how to fix them.

## Make Updates Version-Compatible

Do this before shipping to production

A Live Update can only change your **web layer** — it must stay compatible with the **native binary** already installed on the device. Shipping a bundle that relies on a native feature an older app version doesn't have will **crash the app on launch**. See [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md) for the full rules.

The safest way to prevent this is **versioned channels**: pin each native release to its own channel so a bundle only ever reaches compatible devices. Configure the channel natively at build time, derived from your version code.

On Android, add a resource value in `android/app/build.gradle`:

android/app/build.gradle

```
android {
    defaultConfig {
        resValue "string", "capawesome_live_update_default_channel",
                 "production-" + defaultConfig.versionCode
    }
}
```

On iOS, add a key to `ios/App/App/Info.plist`:

ios/App/App/Info.plist

```
<key>CapawesomeLiveUpdateDefaultChannel</key>
<string>production-$(CURRENT_PROJECT_VERSION)</string>
```

On Electron, set `defaultChannel` in `electron/capacitor.electron.config.ts` — see [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/#versioned-channel).

On Android, set the channel via a `build-extras.gradle` file included through your `config.xml`:

build-extras.gradle

```
android {
    applicationVariants.all { variant ->
        variant.resValue "string", "capawesome_live_update_default_channel",
                         "production-" + variant.versionCode
    }
}
```

On iOS, add the channel key to your `Info.plist` via `config.xml`:

config.xml

```
<platform name="ios">
  <config-file target="*-Info.plist" parent="CapawesomeLiveUpdateDefaultChannel">
    <string>production-$(CURRENT_PROJECT_VERSION)</string>
  </config-file>
</platform>
```

Every native release now ships pinned to its own channel, and uploads to `production-<version>` only reach matching devices. See [Manage Channels](https://capawesome.io/docs/cloud/live-updates/channels/index.md) for alternatives, such as selecting the channel at runtime.

## Next Steps

- **Publish an Update**

  ______________________________________________________________________

  The recurring workflow for shipping updates to your users.

  [Publish an update](https://capawesome.io/docs/cloud/live-updates/publish/index.md)

- **Sign Your Bundles**

  ______________________________________________________________________

  Add code signing so only you can publish updates to your app.

  [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md)

## Bonus: Video Walkthrough

Prefer to watch the setup end-to-end? This walkthrough covers the first deployment, channel setup, and runtime behavior in a real project:

# Troubleshooting

Most Live Update issues can be diagnosed from the [Logs](https://capawesome.io/docs/cloud/live-updates/logs/index.md) view in the Console, which shows each device-to-cloud request, the channel it requested, and the bundle it was served. Start there, then match your symptom below.

## Check the native logs

The SDK also prints diagnostic messages on the device itself. When something doesn't behave as expected, run the app on a device or simulator and watch the native logs for any errors or warnings from the Live Update SDK — they often point straight at the cause:

- **Android** — view Logcat in Android Studio, or run `adb logcat` from the terminal.
- **iOS** — open the Xcode console while the app is running.
- **Electron** — the SDK logs to the main process output, the terminal that started `npx cap run @capawesome/capacitor-electron`. See [Update Electron Apps](https://capawesome.io/docs/cloud/live-updates/electron/#troubleshooting) for desktop-specific issues.

## No update is delivered to the device

Check these causes, roughly in order of likelihood:

1. **Channel mismatch** — the device is subscribed to a different channel than you published to. Check the [Logs](https://capawesome.io/docs/cloud/live-updates/logs/index.md) to see which channel the device requested. This is the most common cause when using versioned channels.
1. **Native-version incompatibility** — the bundle is restricted to a native version range that doesn't include the device. See [Binary-Compatible Changes](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md).
1. **Rollout** — the bundle is at less than 100% and this device isn't in the rollout group. See [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md).
1. **Strategy not triggering** — with `autoUpdateStrategy: none` and no manual `sync()`, no check happens. With `background`, checks are throttled to once every 15 minutes — force-close and restart to trigger one immediately.
1. **Blocked or rolled-back bundle** — `autoBlockRolledBackBundles` blocks a bundle that previously failed to start. See [Roll back a release](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md).
1. **Signature rejected** — if the bundle is signed but the app's configured public key doesn't match, the bundle is rejected. See [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md).
1. **Quota or lifecycle** — your MAU or data transfer [limit](https://capawesome.io/docs/cloud/live-updates/limits/index.md) was reached, or the bundle expired or was deleted.
1. **Network** — the device can't reach Capawesome Cloud, or a custom `serverDomain` is misconfigured. Check the [status page](https://status.capawesome.io) to rule out a service incident.

## An update is downloaded but not applied

The bundle is staged but the WebView still shows the old version. This usually means the app hasn't reloaded yet:

- With `background`, the new bundle is applied on the **next** app launch — force-close and restart.
- If you use a manual strategy, make sure you call `reload()` after the bundle is staged. See [Choose an Update Strategy](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md).

## The app hangs after a reload, but works after a force quit

If the app shows a blank or loading screen after `reload()`, but the update is applied correctly after a force quit, the bundle was most likely applied as expected and the new page is stuck instead. Log the bundle ID returned by `getCurrentBundle()` as early as possible at app start to confirm which bundle is running.

`reload()` reloads the WebView without restarting the native process, so resources of the web layer that hold an exclusive lock are not released automatically and can prevent the new page from starting. A force quit starts a new process and releases these resources, which is why the update seems to be applied only after a restart.

The most common cause is IndexedDB. The Firebase JS SDK, for example, holds an IndexedDB lease as long as Firestore offline persistence is enabled — terminate the client before calling `reload()`. Keep in mind that persistence may be active even if you try to exclude WebViews, because guards that detect the browser by user agent usually also match the `WKWebView` on iOS. On Android, the problem is less likely to occur because Chromium recovers from a stale lease. Other candidates are WebSockets, Web Locks and service workers. If you cannot release these resources, apply the new bundle on the next app launch instead of reloading in place.

## The app crashes or rolls back after an update

- A bundle that depends on a native feature the installed binary doesn't have will crash on launch. Make updates [version-compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md).
- If you use automatic rollback, the app reverts to the built-in bundle shipped with the installed native app version when `ready()` isn't called within `readyTimeout`. Make sure you call `ready()` early at app start. See [Roll back a release](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md).

## Signature verification fails

The bundle's signature doesn't match the public key in your app config. Confirm you're signing with the matching private key and that the public key in your config is correct. See [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md).

## Still stuck?

Reach out via [Support](https://capawesome.io/docs/support/index.md) with the relevant entries from the [Logs](https://capawesome.io/docs/cloud/live-updates/logs/index.md) view.

# Update Strategies

An update *strategy* decides **when** an update is downloaded, **when** it's applied, and **whether the user is involved**. The SDK supports four patterns, from "set it once and forget it" to "push an update on demand". Pick the default that fits your app.

## Background

The simplest option, with no app-side code. Set the `autoUpdateStrategy` option to `background` in your configuration:

capacitor.config.ts

```
const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      autoUpdateStrategy: "background",
      autoBlockRolledBackBundles: true // recommended
    }
  }
};
```

config.xml

```
<preference name="AUTO_UPDATE_STRATEGY" value="background" />
<preference name="AUTO_BLOCK_ROLLED_BACK_BUNDLES" value="true" />
```

This checks for the latest bundle **at app start and on resume** (throttled to once every 15 minutes), downloads it in the background, and applies it on the next launch — no code required. It's the easiest way to keep users up to date.

## Always Latest (recommended)

Get the background strategy's silent download, but prompt the user to apply the update as soon as it's ready instead of waiting for the next cold start. Keep `autoUpdateStrategy` set to `background` and listen for the `nextBundleSet` event:

```
import { LiveUpdate } from "@capawesome/capacitor-live-update";

LiveUpdate.addListener("nextBundleSet", async ({ bundleId }) => {
  if (!bundleId) return;
  if (confirm("A new version is available. Install it now?")) {
    await LiveUpdate.reload();
  }
});
```

```
cordova.plugins.LiveUpdate.addListener("nextBundleSet", async ({ bundleId }) => {
  if (!bundleId) return;
  if (confirm("A new version is available. Install it now?")) {
    await cordova.plugins.LiveUpdate.reload();
  }
});
```

The download happens in the background, so the prompt only appears once the bundle is fully on disk — there's no waiting when the user taps "install".

## Force Update

The "users must be on the latest version before they can use the app" strategy. Keep the splash screen visible while the update check runs, then `sync()` on app start and either `reload()` (if there's an update) or hide the splash:

```
import { SplashScreen } from "@capacitor/splash-screen";
import { LiveUpdate } from "@capawesome/capacitor-live-update";

const { nextBundleId } = await LiveUpdate.sync();
if (nextBundleId) {
  await LiveUpdate.reload();
} else {
  await SplashScreen.hide();
}
```

Disable the splash screen's auto-hide via `SplashScreen: { launchAutoHide: false }` in your config.

```
const { nextBundleId } = await cordova.plugins.LiveUpdate.sync();
if (nextBundleId) {
  await cordova.plugins.LiveUpdate.reload();
} else {
  navigator.splashscreen.hide();
}
```

Keep the splash screen visible with `AutoHideSplashScreen=false` in your `config.xml`.

This guarantees freshness, but every cold start on a slow connection makes the user wait while the bundle downloads. Reserve it for apps where running a stale version is genuinely unsafe. Set `autoUpdateStrategy` to `none` to avoid running two update mechanisms at once.

## Instant

For critical updates, trigger an update with a **silent push notification** that tells the app to check for an update *now*. When the silent notification arrives, call `sync()` and `reload()`. This requires push infrastructure (such as Firebase Cloud Messaging) and is meant as a break-glass tool, not an everyday flow. Set `autoUpdateStrategy` to `none`.

## Further reading

Want to combine Live Updates with native app store updates? See [Capacitor App Updates: The Complete Guide](https://capawesome.io/blog/capacitor-app-update-guide/index.md).

# Integrations

Automate publishing Live Updates from your CI/CD pipeline. The setup is the same across providers — only the pipeline syntax differs.

- **Azure DevOps**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/live-updates/integrations/azure-devops/index.md)

- **Bitbucket Pipelines**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/live-updates/integrations/bitbucket-pipelines/index.md)

- **GitHub Actions**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/live-updates/integrations/github-actions/index.md)

- **GitLab CI/CD**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/live-updates/integrations/gitlab-ci/index.md)

## How it works

Every pipeline follows the same shape:

1. **Authenticate** — create an API token in Capawesome Cloud, store it as a CI secret, and log in with `--token`.
1. **Create the channel** — `apps:channels:create --ignore-errors` is idempotent: it creates the channel on first run and is a no-op afterward.
1. **Build and publish** — let Capawesome Cloud build your web assets in the cloud (`apps:builds:create --platform web`) so every release uses the same environment, or build on the runner and upload with `apps:liveupdates:upload`.

A few recommendations that apply to every provider:

- **Build in the cloud** rather than on the runner, to avoid environment drift.
- **Pin the CLI version** (`@capawesome/cli@<version>`) so pipelines are reproducible.
- **Use `--git-ref`** to associate each bundle with the commit it was built from.
- Prefer **manual dispatch** over auto-on-merge so updates ship when you decide.

For signing, versioned channels, and gradual rollouts in CI, see [Sign your bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md), [Subscribe to a channel](https://capawesome.io/docs/cloud/live-updates/channel-subscription/index.md), and [Roll out gradually](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md).

# Azure DevOps

You can easily publish Live Updates to Capawesome Cloud using [Azure Pipelines](https://azure.microsoft.com/de-de/products/devops/pipelines). In this guide, we will show you how to create a Azure pipeline that builds your web assets and creates a bundle on Capawesome Cloud using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).

## Preparation

Before you start, make sure you have a Capawesome Cloud account and an app set up. Next, you need to create a Capawesome Cloud token and add it to your Azure Pipeline as a secure variable.

### Create a Capawesome Cloud token

Create a new Capawesome Cloud token via the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/tokens). Just navigate to the `Tokens` page in the settings and click on the `Create token` button. Choose a name for the token and click on the `Create` button. The token is now copied to your clipboard.

### Create a Azure Pipeline Variable

Add the Capawesome Cloud token to your Azure Pipeline as a secure variable with the name `CAPAWESOME_CLOUD_TOKEN` as described in [Set secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables).

## Pipeline

### Create the Pipeline

Create a new Azure Pipeline file in your repository under `azure-pipelines.yml` with the following content:

```
trigger: none

parameters:
  - name: channel
    displayName: Channel
    type: string

pool:
  vmImage: ubuntu-latest

jobs:
- job: Deploy
  displayName: Build web assets
  steps:
  - checkout: self
    displayName: Checkout
  - task: UseNode@1
    inputs:
      version: 20.x
    displayName: Install Node.js
  - script: npm ci
    displayName: Install Dependencies
  - script: npm run build
    displayName: Build web assets
  - script: npm install -g @capawesome/cli@latest
    displayName: Install Capawesome CLI
  - script: npx @capawesome/cli apps:channels:create --app-id 00000000-0000-0000-0000-000000000000 --name $env:CHANNEL --ignore-errors
    displayName: Create a channel on Capawesome Cloud
    env:
      CAPAWESOME_CLOUD_TOKEN: $(CAPAWESOME_CLOUD_TOKEN)
      CHANNEL: ${{ parameters.channel }}
  - script: npx @capawesome/cli apps:liveupdates:upload --app-id 00000000-0000-0000-0000-000000000000 --channel $env:CHANNEL --path dist
    displayName: Create a bundle on Capawesome Cloud
    env:
      CAPAWESOME_CLOUD_TOKEN: $(CAPAWESOME_CLOUD_TOKEN)
      CHANNEL: ${{ parameters.channel }}
```

This pipeline will build your web assets, log in to Capawesome Cloud, create a channel (if it does not exist yet), and create a bundle for the specified channel.

### Trigger the Pipeline

You can then trigger the pipeline manually by running it in the Azure Pipelines UI or by using the Azure Pipelines API. You will be prompted to enter the channel name. Of course, you can also trigger the pipeline automatically by specifying a different trigger.

# Bitbucket Pipelines

You can easily publish Live Updates to Capawesome Cloud using [Bitbucket Pipelines](https://www.atlassian.com/de/software/bitbucket/features/pipelines). In this guide, we will show you how to create a Bitbucket pipeline that builds your web assets and creates a bundle on Capawesome Cloud using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).

## Preparation

Before you start, make sure you have a Capawesome Cloud account and an app set up. Next, you need to create a Capawesome Cloud token and add it to your Bitbucket repository as a secure variable.

### Create a Capawesome Cloud token

Create a new Capawesome Cloud token via the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/tokens). Just navigate to the `Tokens` page in the settings and click on the `Create token` button. Choose a name for the token and click on the `Create` button. The token is now copied to your clipboard.

### Create a Bitbucket Repository Variable

Add the Capawesome Cloud token to your Bitbucket repository as an encrypted secret with the name `CAPAWESOME_CLOUD_TOKEN` as described in [Variables and secrets](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/).

## Pipeline

### Create the Pipeline

Create a new Bitbucket Pipeline file in your repository under `bitbucket-pipelines.yml` with the following content:

```
image: node:20

pipelines:
  custom:
    deploy-live-update:
      - variables:
          - name: Channel
      - step:
          name: Build web assets
          caches:
            - node
          script:
            - npm ci
            - npm run build
            - npm install -g @capawesome/cli@latest
            - npx @capawesome/cli apps:channels:create --app-id 00000000-0000-0000-0000-000000000000 --name $Channel --ignore-errors
            - npx @capawesome/cli apps:liveupdates:upload --app-id 00000000-0000-0000-0000-000000000000 --path dist --channel $Channel
```

This pipeline will build your web assets, log in to Capawesome Cloud, create a channel (if it does not exist yet), and create a bundle for the specified channel.

### Trigger the Pipeline

You can then trigger the pipeline manually via the Bitbucket Pipelines UI as described in [Scheduled and manually triggered pipelines](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-triggers/). Of course, you can also trigger the pipeline automatically by specifying specific [Pipeline start conditions](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/).

# GitHub Actions

Publish Live Updates from [GitHub Actions](https://github.com/features/actions). You can use the official **Capawesome Cloud Live Update Action** (recommended) or the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) directly.

## Prerequisites

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in Capawesome Cloud and store it as a repository secret named `CAPAWESOME_TOKEN`. See [Creating encrypted secrets for a repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-encrypted-secrets-for-a-repository).

## Workflow

Build your web assets, then publish them as a Live Update bundle.

The official [`cloud-live-update-action`](https://github.com/capawesome-team/cloud-live-update-action) wraps the upload in a single step — and creates the channel automatically if it doesn't exist yet:

.github/workflows/deploy-live-update.yml

```
name: Deploy Live Update
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: capawesome-team/cloud-live-update-action@v0.1.0
        with:
          appId: "00000000-0000-0000-0000-000000000000"
          channel: production
          path: dist
          gitRef: ${{ github.sha }}
          token: ${{ secrets.CAPAWESOME_TOKEN }}
```

The action exposes all the upload options as inputs — including `privateKey` for [code signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md), `rolloutPercentage` for [gradual rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md), and native version constraints to keep updates [version-compatible](https://capawesome.io/docs/cloud/live-updates/binary-compatible-changes/index.md). See the [action README](https://github.com/capawesome-team/cloud-live-update-action) for the full list.

Prefer full control, or running on a non-GitHub CI? Use the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) directly:

.github/workflows/deploy-live-update.yml

```
name: Deploy Live Update
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: npx @capawesome/cli login --token ${{ secrets.CAPAWESOME_TOKEN }}
      - run: npx @capawesome/cli apps:channels:create --app-id 00000000-0000-0000-0000-000000000000 --name production --ignore-errors
      - run: npx @capawesome/cli apps:liveupdates:upload --app-id 00000000-0000-0000-0000-000000000000 --path dist --channel production
```

Pin the action (or the CLI version) to a specific release for reproducible runs. Trigger on `push` for automatic releases, or use `workflow_dispatch` to publish on demand.

# GitLab CI/CD

You can easily publish Live Updates to Capawesome Cloud using [GitLab CI/CD](https://docs.gitlab.com/ci/). In this guide, we will show you how to create a GitLab CI/CD pipeline that builds your web assets and creates a bundle on Capawesome Cloud using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).

## Preparation

Before you start, make sure you have a Capawesome Cloud account and an app set up. Next, you need to create a Capawesome Cloud token and add it to your GitLab project as a CI/CD variable.

### Create a Capawesome Cloud token

Create a new Capawesome Cloud token via the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/tokens). Just navigate to the `Tokens` page in the settings and click on the `Create token` button. Choose a name for the token and click on the `Create` button. The token is now copied to your clipboard.

### Create a GitLab CI/CD Variable

Add the Capawesome Cloud token to your GitLab project as a CI/CD variable with the name `CAPAWESOME_CLOUD_TOKEN` as described in [CI/CD variables](https://docs.gitlab.com/ci/variables/). Make sure to mark the variable as masked and protected.

## Pipeline

### Create the Pipeline

Create a new GitLab CI/CD pipeline file in your repository under `.gitlab-ci.yml` with the following content:

```
spec:
  inputs:
    channel:
      description: The name of the channel to deploy the update to.
      default: production
---
stages:
  - deploy

deploy-live-update:
  stage: deploy
  image: node:20
  before_script:
    - npm ci
    - npm run build
    - npm install -g @capawesome/cli@latest
  script:
    - npx @capawesome/cli apps:channels:create --app-id 00000000-0000-0000-0000-000000000000 --name $[[ inputs.channel ]] --ignore-errors
    - npx @capawesome/cli apps:liveupdates:upload --app-id 00000000-0000-0000-0000-000000000000 --path dist --channel $[[ inputs.channel ]]
```

This pipeline will build your web assets, log in to Capawesome Cloud (using the `CAPAWESOME_CLOUD_TOKEN` environment variable), create a channel (if it does not exist yet), and create a bundle for the specified channel.

### Trigger the Pipeline

You can run the pipeline manually by navigating to the `CI/CD` > `Pipelines` section in your GitLab project and clicking on the `Run pipeline` button. You will be prompted to enter the channel name as a variable. Of course, you can also trigger the pipeline automatically by using different rules like `push` or `merge_request`.

# Migrating from Ionic Appflow

This guide walks you through migrating your apps from Ionic Appflow to Capawesome Cloud. Most of the work is automated: the Capawesome CLI imports your Appflow organization export — apps, signing certificates, environments, channels, configurations, store destinations, and automations — with a single command. The remaining steps are swapping the Live Update SDK in your app and reconnecting your Git provider.

Ionic Appflow reaches end of life on December 31, 2027

Ionic [announced the discontinuation](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) of its commercial products, including Appflow, and stopped selling to new customers in February 2025. [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Appflow and its Enterprise plugins. Read the [partnership announcement](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) and [why teams are switching to Capawesome Cloud](https://capawesome.io/blog/migrating-from-ionic-appflow-to-capawesome-cloud/index.md) for the background.

Using Ionic Enterprise plugins?

Auth Connect, Identity Vault, and Secure Storage are discontinued along with Appflow. See [Alternatives to the Ionic Enterprise plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/index.md) for drop-in replacements from Capawesome.

AI-Assisted Migration

For a guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill ionic-appflow-migration` and ask your preferred AI coding assistant to use the `ionic-appflow-migration` skill.

## Video Walkthrough

This video shows the migration from start to finish: exporting your organization from the Appflow dashboard, previewing the import, and running it against Capawesome Cloud.

## Prerequisites

Before you begin, make sure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
- The latest version of the Capawesome CLI [installed](https://capawesome.io/docs/cloud/cli/installation/index.md) and [authenticated](https://capawesome.io/docs/cloud/cli/authentication/index.md).
- Admin access to your Ionic Appflow organization.

## Step 1: Export Your Ionic Appflow Organization

Ionic Appflow can export the configurations of all apps in your organization as a zip file:

1. Open the [Ionic Appflow Dashboard](https://dashboard.ionicframework.com) and select your organization.
1. Navigate to **Settings** → **Account**.
1. In the **Organization export** section, click **Export**.
1. Once the export completes, click **Download** to save the zip file.

The export contains sensitive data

The zip file includes your environment secrets, signing certificates with their passwords, and store credentials in plain text. Store it securely and delete it after the migration.

## Step 2: Preview the Import

Use the [`apps:import`](https://capawesome.io/docs/cloud/cli/commands/#appsimport) command with the `--dry-run` option to preview what will be imported without creating any resources:

```
npx @capawesome/cli apps:import --file appflow-export.zip --dry-run
```

The CLI prints a summary table with the resources it found for each app, along with any warnings. To import only specific apps, pass the `--include` option with the app names or IDs from the export:

```
npx @capawesome/cli apps:import --file appflow-export.zip --include "My App" --dry-run
```

## Step 3: Run the Import

Run the same command without `--dry-run` to import the apps into your organization:

```
npx @capawesome/cli apps:import --file appflow-export.zip
```

The command creates the following resources in Capawesome Cloud:

| Ionic Appflow                     | Capawesome Cloud    | Notes                                                          |
| --------------------------------- | ------------------- | -------------------------------------------------------------- |
| App                               | App                 | Name conflicts are resolved with a numeric suffix              |
| Live update channel               | Channel             | Same concept, same naming freedom                              |
| Environment (variables & secrets) | Environment         | Variables and secrets are both imported                        |
| Signing certificate               | Signing certificate | Keystores, `.p12` files, and provisioning profiles             |
| Native config                     | Configuration       | App name and bundle ID overrides                               |
| Destination                       | Destination         | Store credentials incl. the Google service account key         |
| Native and web build automation   | Automation          | A web automation with multiple channels keeps all its channels |
| Repository association            | Git repository link | Requires a connected Git provider (see below)                  |
| Latest build number               | Next build number   | New builds continue your Appflow build numbering               |

If an app was exported with the app type `ionic`, the CLI asks whether it is a Capacitor or Cordova app, since Appflow used this type for both. In non-interactive environments, pass the `--ionic-app-type` option instead.

## Step 4: Review the Import Summary

After the import, the CLI prints a summary with the created resources and any warnings. The most common warnings:

- **Automation webhooks were not imported**: Capawesome Cloud supports [webhooks](https://capawesome.io/docs/cloud/webhooks/index.md) at the app level instead of per automation. Add them manually after the import.
- **Live Update plugin settings**: Appflow native configs can contain Live Update plugin settings. In Capawesome Cloud, this configuration lives in your app (see [Step 5](#step-5-update-your-app)).
- **Repository could not be linked**: The Git provider must be connected first (see below).
- **React Native and Flutter apps were skipped**: Support is coming soon. Re-run the import with the `--include` option once available to import the remaining apps.

## Step 5: Update Your App

The Capawesome Live Update SDK keeps Appflow's `sync()` and `reload()` API, so many teams complete this step quickly. Remove the Appflow SDK and install the Capawesome equivalent:

```
npm uninstall @capacitor/live-updates
npm install @capawesome/capacitor-live-update
npx cap sync
```

Then update your [Capacitor configuration](https://capacitorjs.com/docs/config) file:

capacitor.config.ts

```
import { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: "00000000-0000-0000-0000-000000000000", // Replace with your Capawesome app ID
      defaultChannel: "production",
      autoUpdateStrategy: "background",
      autoBlockRolledBackBundles: true,
      readyTimeout: 10000
    }
  }
};

export default config;
```

```
cordova plugin remove cordova-plugin-ionic
cordova plugin add @capawesome/cordova-live-update --variable APP_ID=<your-app-id>
```

Then set the plugin variables as `<preference>` entries in your `config.xml`:

```
<preference name="APP_ID" value="00000000-0000-0000-0000-000000000000" />
<preference name="DEFAULT_CHANNEL" value="production" />
<preference name="AUTO_UPDATE_STRATEGY" value="background" />
<preference name="AUTO_BLOCK_ROLLED_BACK_BUNDLES" value="true" />
<preference name="READY_TIMEOUT" value="10000" />
```

Here's how the most common configuration options map between the two platforms:

| Ionic Appflow      | Capawesome Cloud     | Notes                                          |
| ------------------ | -------------------- | ---------------------------------------------- |
| `appId`            | `appId`              | Same purpose, different value                  |
| `channel`          | `defaultChannel`     | Same purpose, renamed                          |
| `autoUpdateMethod` | `autoUpdateStrategy` | Set to `background`, or handle updates in code |
| `maxVersions`      | `autoDeleteBundles`  | A boolean instead of a number                  |
| `enabled`          | Not needed           | Handled in code                                |

The `readyTimeout` and `autoBlockRolledBackBundles` options enable [automatic rollback](https://capawesome.io/docs/cloud/live-updates/rollbacks/index.md) of broken updates. For automatic rollback to work, call `ready()` as early as possible at app start. The SDK exposes the same `sync()` and `reload()` methods as the Appflow SDK, so most call sites change only their import — see [Update Strategies](https://capawesome.io/docs/cloud/live-updates/update-strategies/index.md) for more ways to apply updates.

## Step 6: Complete the Manual Steps

A few things cannot be imported and need a one-time manual setup:

- **Connect your Git provider**: Create an organization-level [Git connection](https://console.cloud.capawesome.io/organizations/_/git) for GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, or any Git server over HTTP/S (see [Integrations](https://capawesome.io/docs/cloud/integrations/index.md)), then select the repository on the **Git repository** page of each app. If the import could not link a repository, this is why.
- **Add app-level webhooks**: If your Appflow automations used webhooks, [set them up](https://capawesome.io/docs/cloud/webhooks/setup/index.md) at the app level.
- **Apple App Store API key**: The import carries over Apple ID credentials. For automated publishing, an [App Store Connect API key](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/index.md) (`.p8` file) is the more robust choice — add it to your imported destination.
- **API tokens for CI/CD**: Replace your Appflow personal access tokens with [Capawesome Cloud API tokens](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in your pipelines.

## Step 7: Check Your Native Build Setup

Native builds in Capawesome Cloud work much like in Appflow. Check these differences before your first build:

- **Commit the native platform folders**: Like Appflow, Capawesome Cloud runs `npx cap sync` but never `npx cap add`. The `android` and `ios` folders of your Capacitor app must be committed to your repository. If a build fails with `android platform has not been added yet`, check your `.gitignore` and any script that creates the platform during the build.
- **Use the Capawesome Cloud names for tool versions**: Capawesome Cloud reads `NODE_VERSION` and `JAVA_VERSION` instead of Appflow's `OVERRIDE_NODE_VERSION` and `OVERRIDE_JAVA_VERSION`. The import renames them automatically. If you created environments manually, rename these variables yourself (see [Reserved variables](https://capawesome.io/docs/cloud/native-builds/environment-variables/#reserved-variables)).
- **Android builds run on macOS**: Appflow built Android apps on Linux, while Capawesome Cloud runs every build on a [macOS build stack](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md). Shell scripts in your build, such as an npm `prebuild` hook, now use the BSD versions of tools like `sed` and `wc`. For example, `sed -i` requires a backup suffix on macOS (`sed -i '' ...`), and `wc -l` pads its output with spaces. Start such scripts with `set -e` so that a failing command stops the build right away instead of causing a misleading error later.

## Step 8: Verify the Migration

Run one build, one live update, and one submission to confirm everything works end to end:

```
npx @capawesome/cli apps:builds:create --platform android --git-ref main
npx @capawesome/cli apps:liveupdates:upload --channel production
npx @capawesome/cli apps:deployments:create --build-number 1 --destination "Google Play"
```

You can run Appflow and Capawesome Cloud in parallel during the transition: ship a new app release with the Capawesome Live Update SDK while older binaries keep receiving updates from Appflow — no big-bang cutover required.

## What Is Not Migrated

The following Appflow data has no equivalent in the export and is not imported: build history, live update deployment history, team and member assignments, and dependency caching settings. Your apps in Ionic Appflow remain untouched by the import.

## Get Help With Your Migration

Want a hand moving off Appflow? Our team can walk you through the migration and answer questions specific to your Capacitor, Cordova, or native setup.

[Book an Ionic Appflow Migration Demo](https://cal.com/team/capawesome/ionic-appflow-migration)

## Next steps

- [CLI Command Reference](https://capawesome.io/docs/cloud/cli/commands/#appsimport) — all options of the `apps:import` command.
- [Getting Started with Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/index.md) — publish your first update after the SDK swap.
- [Getting Started with Native Builds](https://capawesome.io/docs/cloud/native-builds/setup/index.md) — trigger your first cloud build.
- [Getting Started with App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/setup/index.md) — submit your first build to the stores.

# Native Builds

Use [Capawesome Cloud](/) to build native iOS and Android apps in the cloud. Native Builds supports Capacitor, Cordova, and native iOS and Android projects (see the [sample projects](https://capawesome.io/docs/cloud/native-builds/sample-projects/index.md)). Get faster builds with optimized runner images, automatic signing and provisioning, and seamless integration with your Git provider.

## Features

- 🚀 **Optimized Build Stacks**: Pre-configured with the latest stable versions of Node.js, Java, and Xcode running on the latest macOS with M4 instances.
- 🔗 **Universal Git Integration**: Connect GitHub, GitLab, Bitbucket, or Azure DevOps—including self-hosted and enterprise instances.
- 🔐 **Signing & Provisioning**: Securely manage Android keystores and iOS certificates for all build types.
- ⚙️ **Advanced Configuration**: Simple `capawesome.config.json` with support for monorepos, custom build commands, and environment variables.
- 🔒 **Encrypted Secrets**: Store sensitive data like API keys and tokens securely, never exposed in logs.
- 📦 **Artifact Management**: All build outputs are stored securely and available for download.
- 🪵 **Detailed Job Logs**: Comprehensive, easy-to-read logs make debugging straightforward.
- 🏃 **Isolated Build Environments**: Every build runs in its own isolated environment for security and consistency.
- 📱 **All Build Types**: Support for iOS Simulator, Development, Ad Hoc, App Store, and Enterprise builds, plus Android Debug, Release, and custom build types.
- 📚 **Documentation**: Comprehensive documentation to help you get started.

## Getting Started

- **Setup Native Builds**

  ______________________________________________________________________

  Create your first native build with Capawesome Cloud Native Builds.

  ______________________________________________________________________

  [Getting Started](https://capawesome.io/docs/cloud/native-builds/setup/index.md)

## Documentation

- **App Configuration**

  ______________________________________________________________________

  Learn how to configure your app builds using `capawesome.config.json`.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/configuration/index.md)

- **Build Types**

  ______________________________________________________________________

  Understand the different build types available for iOS and Android.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/build-types/index.md)

- **Build Stacks**

  ______________________________________________________________________

  Learn about the software versions and tools available in each build stack.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md)

- **Signing Certificates**

  ______________________________________________________________________

  Configure signing certificates and provisioning profiles for your apps.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/certificates/index.md)

- **Environments**

  ______________________________________________________________________

  Use environment variables and secrets to customize your builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/environments/index.md)

- **Native Configurations**

  ______________________________________________________________________

  Set the app name and package name of your native project before it is built.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md)

- **Share a Build**

  ______________________________________________________________________

  Give external testers a public link to view and install a build without an account.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md)

- **Troubleshooting**

  ______________________________________________________________________

  Find solutions to common build issues and errors.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md)

- **CI/CD Integrations**

  ______________________________________________________________________

  Trigger native builds from GitHub Actions, GitLab CI, and more.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/integrations/index.md)

- **FAQ**

  ______________________________________________________________________

  Find answers to frequently asked questions about Capawesome Cloud Native Builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/faq/index.md)

## Guides

Here are some guides to help you get started with Capawesome Cloud Native Builds:

- [Announcing Capawesome Cloud Native Builds](https://capawesome.io/blog/announcing-capawesome-cloud-native-builds/index.md)

# Publish Android App Bundles

The [Android App Bundle](https://developer.android.com/guide/app-bundle/app-bundle-format) (`.aab`) is the publishing format Google Play **requires for new apps** since August 2021, and the recommended format for all apps. Capawesome Cloud builds an AAB alongside the APK for every Android application module, so no configuration is needed — you just pick the AAB when you publish. Projects with a Wear OS, Android TV, or Automotive module get one AAB per module; see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

## Why app bundles

- **Required by Google Play**: New apps must be published as app bundles. APK uploads are only still accepted for apps that existed before the requirement.
- **Smaller downloads**: Google Play generates APKs optimized for each device configuration and language from your bundle, so users download only what they need.
- **Metadata included**: The bundle carries build metadata for Google Play — most notably the R8/ProGuard mapping file used to deobfuscate crash reports automatically (see [Code shrinking with R8](#code-shrinking-with-r8)).

## Download the AAB

Use [`apps:builds:download`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsdownload) with the `--aab` flag — optionally followed by a file path:

```
npx @capawesome/cli apps:builds:download --aab ./app.aab
```

For a project with a phone module this downloads the phone AAB. Add `--form-factor` to download the AAB of a Wear OS, Android TV, or Automotive module instead.

Open the build's detail page from the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page and download the AAB artifact. Builds with several application modules list one artifact per form factor.

See [Monitor a build](https://capawesome.io/docs/cloud/native-builds/monitor-builds/index.md) for more on working with finished builds.

## Publish to Google Play

You can publish the AAB in two ways:

- **Manually**: Download the AAB and upload it to a release in Google Play Console.
- **Automatically**: Set up a [Google Play destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md) with the publishing format `AAB` and let Capawesome Cloud [submit your builds](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md) for you.

A submission uploads every AAB of the build. Apps with more than one application module are released to one track per form factor — see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

## Migrate an existing app from APK

If your app still publishes APKs, enroll it in [Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756) in Google Play Console — you upload your existing app signing key once, and Google Play signs the APKs it generates from your bundles with it. From then on, upload app bundles instead of APKs.

Nothing changes in Capawesome Cloud: keep signing your builds with the same keystore as before (see [Android signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md)). It simply becomes your upload key.

## Code shrinking with R8

To shrink and obfuscate your app with R8, enable minification for the release build type in your app module's `build.gradle` file (for Capacitor projects, `android/app/build.gradle`):

```
android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}
```

R8 renames classes and methods during the build, which makes production stack traces unreadable. To deobfuscate them, Google Play needs the mapping file generated by that exact build. When you publish an AAB, this happens automatically: the mapping file is embedded in the bundle's `BUNDLE-METADATA/` directory, and Google Play extracts and applies it to crash and ANR reports — you never have to handle a `mapping.txt` file yourself.

Note

When publishing an APK, Google Play requires you to upload the `mapping.txt` file manually. The mapping file is not available as a separate build artifact in Capawesome Cloud — publish an Android App Bundle instead, which includes it automatically.

## Next steps

- [Monitor a build](https://capawesome.io/docs/cloud/native-builds/monitor-builds/index.md) — track status and download artifacts.
- [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md) — one AAB per application module.
- [Set up signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md) — sign your release builds.
- [Google Play destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md) — submit AABs to Google Play automatically.

# Auto-Increment Build Numbers

Capawesome Cloud provides automatic build number incrementing through the `CI_BUILD_NUMBER` environment variable, which increments with each build. This guide shows you how to automatically apply this build number to your native Android and iOS projects.

## Prerequisites

This guide assumes you have already set up Trapeze. If you haven't done this yet, follow the [Advanced: Trapeze](https://capawesome.io/docs/cloud/native-builds/native-configurations/#advanced-trapeze) section of the Native Configurations guide first to:

1. Install Trapeze
1. Set up the build script in your `package.json`

App name and package name

Build numbers and version names need Trapeze. To change the app name or the package name (the application ID on Android, the bundle ID on iOS), you don't — use a [native configuration](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md) instead.

## Configuration

Create a configuration file named `capawesome.yml` in the root of your project with the following content:

```
vars:
  CI_BUILD_NUMBER:
    default: 1

platforms:
  android:
    versionCode: $CI_BUILD_NUMBER
  ios:
    buildNumber: $CI_BUILD_NUMBER
```

This configuration maps the `CI_BUILD_NUMBER` environment variable to the version code on Android and the build number on iOS. On Android, the mapping reaches the phone module only. A Wear OS, Android TV, or Automotive module needs a version code of its own — see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

Default value

The default value of `1` is used for local development when the `CI_BUILD_NUMBER` environment variable is not set. In Capawesome Cloud, this variable is automatically provided and increments with each build.

## How It Works

When you trigger a build in Capawesome Cloud:

1. The `CI_BUILD_NUMBER` environment variable is automatically set to a sequential number
1. The [web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) runs Trapeze with your configuration
1. Trapeze updates the native project files with the current build number
1. Your app is built with the incremented build number

This ensures each build has a unique, incrementing build number without manual intervention.

## Custom Starting Number

If you need to start incrementing from a specific number (for example, to continue from your current build number), you can set the next build number directly in the [app settings](https://console.cloud.capawesome.io/apps/_/settings). The next build number must be at least `1` higher than the previous build number, or `1` if no build has been created yet.

Alternatively, you can add an offset to the `CI_BUILD_NUMBER` variable in your build script:

```
{
  "scripts": {
    "capawesome:build": "CI_BUILD_NUMBER=$(($CI_BUILD_NUMBER + 1000)); if [ \"$CI_PLATFORM\" = \"ios\" ] || [ \"$CI_PLATFORM\" = \"android\" ]; then npx trapeze run capawesome.yml -y --$CI_PLATFORM; fi && npm run build"
  }
}
```

Replace `1000` with your desired offset. For example, if your current build number is 150 and you want the next build to be 151, use an offset of 150.

## Version Name and Build Number

You can combine build number incrementing with version name management:

```
vars:
  VERSION_NAME:
  CI_BUILD_NUMBER:
    default: 1

platforms:
  android:
    versionName: $VERSION_NAME
    versionCode: $CI_BUILD_NUMBER
  ios:
    version: $VERSION_NAME
    buildNumber: $CI_BUILD_NUMBER
```

Then set the `VERSION_NAME` variable in your Capawesome Cloud environment (e.g., `1.0.0`). This way:

- The version name (e.g., `1.0.0`) remains consistent across builds
- The build number increments automatically with each build

# Build Logs

Every native build produces a full log of the build process. Use it to understand what happened during a build and to debug failures.

## View the logs

Print the logs for a build with the [`apps:builds:logs`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildslogs) command:

```
npx @capawesome/cli apps:builds:logs
```

Open the build's detail page from the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page. You can follow the logs live while the build runs and review them after it finishes.

## Debugging a failed build

For a failed build, the fastest path is [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md), which summarizes the cause and a suggested fix from the logs. For common errors and manual fixes, see [Troubleshooting](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md).

# Build Stacks

In Capawesome Cloud, build stacks define a set of pre-configured software versions and tools used during the native build process. Selecting the appropriate build stack ensures compatibility with your application's dependencies and requirements.

Available Build Stacks

Capawesome Cloud currently offers **three build stacks**: `macos-sequoia`, `macos-tahoe`, and `macos-golden-gate`. `macos-sequoia` is deprecated and will be removed when the next build stack is released. Move your builds to `macos-tahoe` or `macos-golden-gate` before then. If you have specific requirements or suggestions for build stacks, please [contact us](/contact/).

## Select a Build Stack

Each build runs on a single build stack. If you don't select one, Capawesome Cloud uses the app's default build stack, or `macos-golden-gate` if the app has none. To run a build on a specific stack, choose it when you trigger the build:

Pass the `--stack` flag to [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate):

```
npx @capawesome/cli apps:builds:create --stack macos-tahoe
```

Open the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page, start a build, and select the build stack from the build options:

## Set a Default Build Stack

You can set a default build stack that applies to every build that doesn't select one, for example to keep an app on `macos-tahoe` until it's ready for Xcode 27 without passing `--stack` on every build.

Pass the `--stack` flag to [`apps:update`](https://capawesome.io/docs/cloud/cli/commands/#appsupdate). An empty value restores the Capawesome Cloud default:

```
npx @capawesome/cli apps:update --app-id <APP_ID> --stack macos-tahoe
```

Open your app's **Settings**, and in the **Builds** section enable the **Default build stack** toggle, select the build stack, and save.

Capawesome Cloud resolves the build stack for a build in this order:

1. The build stack selected for the build or automation.
1. The app's default build stack.
1. `macos-golden-gate`, Capawesome Cloud's default build stack.

An [automation](https://capawesome.io/docs/cloud/automations/index.md) without a build stack follows the same order. To set the default programmatically, update the `buildStack` property of the app through the [API](https://capawesome.io/docs/cloud/api/index.md) at `/v1/apps/{appId}`.

## Build Stack Lifecycle

When we release a new build stack, the oldest remaining stack is deprecated, and the new stack becomes the default shortly after. A deprecated stack keeps working until the next build stack is released, then it's removed. Builds that still select a removed stack fail, so switch them to a supported stack before that happens.

## Configurations

The following table lists the software and their respective versions included in each build stack:

| Software                   | macos-sequoia (deprecated)     | macos-tahoe                    | macos-golden-gate (default)    |
| -------------------------- | ------------------------------ | ------------------------------ | ------------------------------ |
| Android Build Tools        | 34.0.0, 35.0.0, 36.0.0, 37.0.0 | 34.0.0, 35.0.0, 36.0.0, 37.0.0 | 34.0.0, 35.0.0, 36.0.0, 37.0.0 |
| Android CMake              | 3.22.1                         | 3.22.1                         | 3.22.1                         |
| Android Command-line Tools | 14742923                       | 14742923                       | 16111833                       |
| Android NDK                | 28.2.13676358                  | 28.2.13676358                  | 28.2.13676358                  |
| Android Platforms          | 34, 35, 36, 37.0               | 34, 35, 36, 37.0               | 34, 35, 36, 37.0               |
| Capacitor CLI              | 8.4.0                          | 8.4.0                          | 8.5.2                          |
| Capawesome CLI             | 4.11.0                         | 4.11.0                         | 4.18.4                         |
| CocoaPods                  | 1.16.2                         | 1.16.2                         | 1.17.0                         |
| Cordova CLI                | 13.0.0                         | 13.0.0                         | 13.0.0                         |
| Fastlane                   | 2.226.0                        | 2.232.2                        | 2.240.1                        |
| Firebase CLI               | 15.31.0                        | 15.31.0                        | 15.31.0                        |
| Ionic CLI                  | 7.2.1                          | 7.2.1                          | 7.2.1                          |
| Java                       | 17, 21 (default)               | 17, 21 (default)               | 17, 21 (default)               |
| macOS                      | 15                             | 26                             | 27                             |
| Node.js                    | 20, 22, 24 (default)           | 20, 22, 24 (default)           | 22, 24 (default), 26           |
| npm                        | 11.6.1                         | 11.9.0                         | 11.19.1                        |
| Ruby                       | 3.3.10                         | 3.3.10                         | 3.3.12                         |
| Trapeze Configure          | 7.1.4                          | 7.1.4                          | 7.1.10                         |
| Xcode                      | 16.4 (default), 26.3           | 26.5 (default), 27.0           | 27.0 (default)                 |

Capawesome Cloud regularly updates the build stacks to include the latest stable versions of the software. When we make changes to a build stack, we'll let you know so you can review them and adjust your build configuration if needed. For the most up-to-date information on the available build stacks and their configurations, please refer to this documentation or contact our support team.

Customizing Versions

You can override the default versions for Java, Node.js, and Xcode by setting the corresponding environment variables (`JAVA_VERSION`, `NODE_VERSION`, `XCODE_VERSION`) in your build configuration. For more information, see the [Environments](https://capawesome.io/docs/cloud/native-builds/environment-variables/#reserved-variables) documentation.

Additional Tools

Each build stack also includes the following tools. Their versions are not pinned and are updated to the latest stable release on each image rebuild: Bundler, Carthage, Git LFS, Gradle, SwiftFormat, SwiftLint, xcbeautify, and xcpretty. The package managers Yarn and pnpm (via Corepack) and bun are available alongside npm.

# Build Types

Build types determine how your app is compiled and signed, affecting its behavior and distribution method. When creating a build in Capawesome Cloud, you select the appropriate build type based on your needs.

## Android Build Types

The selected build type applies to every application module of the project, including a [Wear OS, Android TV, or Automotive module](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

### Debug

The Debug build type is optimized for development and testing. It includes debugging information, is not optimized for performance, and is signed with a debug keystore. Use this type during active development when you need to test features quickly.

### Release

The Release build type is optimized for production deployment. It includes code optimization, [obfuscation](https://capawesome.io/docs/cloud/native-builds/android-app-bundles/#code-shrinking-with-r8) (if configured), and must be signed with your release keystore. This build type is **required for publishing** to the Google Play Store.

### Custom

Custom build types allow you to define additional build variants beyond Debug and Release. For example, you might create a `staging` build type for pre-production testing or a `qa` build type for quality assurance with specific configurations.

To use a custom build type, set the `ANDROID_BUILD_TYPE` environment variable to your custom build type name. Learn more about environment variables in the [Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md) documentation.

## iOS Build Types

### Simulator

Simulator builds are compiled for the iOS Simulator on macOS. These builds run on your development machine and are useful for rapid testing during development without needing a physical device. Simulator builds **cannot be installed** on actual iOS devices. See [Run on an emulator or simulator](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md) to start one from the CLI.

### Development

Development builds are signed with a development certificate and can be installed on devices registered in your Apple Developer account. This build type is ideal for testing on physical devices during development, allowing you to test device-specific features like camera, GPS, and push notifications.

### Ad Hoc

Ad Hoc builds are signed with a distribution certificate and can be distributed to a limited number of devices (up to 100) registered in your Apple Developer account. This build type is perfect for beta testing with a specific group of users outside of TestFlight, or for internal distribution to team members.

### App Store

App Store builds are signed with a distribution certificate and are intended for submission to the App Store. When you deploy this build type through [App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md), it is sent to **TestFlight** rather than directly to the App Store. From there, you can share it with testers or promote it to the App Store for production release.

### Enterprise

Enterprise builds are signed with an Apple Developer Enterprise certificate and can be distributed internally within your organization without going through the App Store. This build type is only available if you have an **Apple Developer Enterprise Program membership** and is designed for in-house distribution to employees.

# Build without Git Connection

Capawesome Cloud [Native Builds](https://capawesome.io/docs/cloud/index.md) typically clone your Git repository to run a build. With the `--path` option, you can upload local source files directly instead of cloning from a Git repository.

This is useful when:

- You don't have access to a Mac and want to build iOS apps from your local machine.
- You want to create debug or test builds without pushing to your remote repository first.
- Your Git server is behind a firewall and you don't want to set up tunnels or mirroring (see [Access Git Behind a Firewall](https://capawesome.io/docs/cloud/native-builds/firewall-access/index.md)).
- You're using a third-party CI/CD system that already checks out the code and you want to trigger builds from there.

## How It Works

When you use the `--path` option, the CLI packages the contents of the specified directory into a compressed archive (respecting your `.gitignore` rules to exclude unnecessary files), uploads it to Capawesome Cloud, and triggers the build using those files instead of cloning from Git.

## Limitations

Builds triggered with `--path` have the following limitations:

- **No Git information**: The Cloud UI will not display Git-related metadata (commit SHA, branch, author) for the build.
- **No Automations**: Builds from local files cannot be used with the [Automations](https://capawesome.io/docs/cloud/automations/index.md) feature, which relies on Git events.
- **No UI-triggered builds**: You cannot trigger or re-run these builds from the Cloud Console. They can only be started via the CLI.
- **Cannot combine with `--git-ref`**: The `--path` and `--git-ref` options are mutually exclusive.

## Usage

To trigger a build from your local source files, run the following command from your project directory:

```
npx @capawesome/cli apps:builds:create \
    --app-id <app-id> \
    --path . \
    --platform <platform> \
    --type <type>
```

Replace the following placeholders:

- `<app-id>`: The ID of your app in Capawesome Cloud.
- `<platform>`: The target platform (`android`, `ios`, or `web`).
- `<type>`: The build type (e.g. `debug`, `release` for Android; `simulator`, `development`, `ad-hoc`, `app-store` for iOS). Not required for web builds.

You can combine `--path` with other options like `--certificate`, `--environment`, or `--stack` just as you would for a regular Git-based build. Refer to the [CLI documentation](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) for the full list of available options.

# Trigger a Build

Triggering a build hands your source code to Capawesome Cloud, which checks it out, installs your dependencies, compiles it on a hosted macOS machine, and hands back the finished artifacts — an `.apk` and `.aab` per Android application module, an `.ipa` for iOS, or a `.zip` of web assets. You never have to keep a Mac or a build toolchain running yourself.

You can start a build two ways — with the [CLI](https://capawesome.io/docs/cloud/cli/index.md) or in the [Console](https://console.cloud.capawesome.io) — and from two sources: your connected **Git repository** (recommended) or **local files** when you don't have a repository connection.

## Prerequisites

Before your first build, make sure you've [created an app](https://capawesome.io/docs/cloud/native-builds/setup/#step-1-create-an-app) and, for Git-based builds, [connected your repository](https://capawesome.io/docs/cloud/native-builds/setup/#step-2-connect-git-repository). Local builds (`--path`) work without a repository connection.

## Build from Git

Building from Git is the recommended path: the Cloud checks out the exact reference you specify, so what ships always matches what's committed.

Use the [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) command and point it at a branch, tag, or commit SHA:

```
npx @capawesome/cli apps:builds:create --platform ios --git-ref main --type development
```

The CLI prompts for any values you don't pass, then streams the build status and prints the build number (e.g. `#42`) when it's done. Add `--detached` to return immediately without waiting, or `--yes` to skip all prompts — handy in scripts and CI.

Open the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page, click **Build from Git**, then choose the Git reference (branch, tag, or commit), the platform, and the [build type](https://capawesome.io/docs/cloud/native-builds/build-types/index.md). Click **Build** to start.

## Build from local files

If you haven't connected a Git repository — or you want to build code that isn't committed yet — build straight from your machine by passing `--path` instead of `--git-ref`:

```
npx @capawesome/cli apps:builds:create --platform android --path . --type debug
```

The CLI zips up the given directory and uploads it as the build source. See [Build without Git](https://capawesome.io/docs/cloud/native-builds/build-without-git/index.md) for the details and caveats.

## Choose what to build

A build is shaped by a handful of options. Pass them as flags on the CLI, or pick them in the Console dialog:

- **Platform** (`--platform`) — `android`, `ios`, or `web`. A web build produces the bundle used for [Live Updates](https://capawesome.io/docs/cloud/live-updates/index.md).
- **Build type** (`--type`) — for Android, `debug` or `release`; for iOS, `simulator`, `development`, `ad-hoc`, `app-store`, or `enterprise`. Pick a debug/simulator type for quick testing and a signed type for distribution. See [Build types](https://capawesome.io/docs/cloud/native-builds/build-types/index.md).
- **Signing certificate** (`--certificate`) — required for signed builds. See [Certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md).
- **Native configuration** (`--configuration`) — the app name and package name (application ID on Android, bundle ID on iOS) to apply to the native project before it's built. Android and iOS only. See [Native configurations](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md).
- **Environment** (`--environment`) — the variables and secrets to expose during the build. You can also pass one-off values with `--variable key=value` or a `.env` file via `--variable-file`. See [Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md).
- **Build stack** (`--stack`) — the macOS image (and its Xcode, Node.js, and Java versions) to build on. Defaults to the app's [default build stack](https://capawesome.io/docs/cloud/native-builds/build-stacks/#set-a-default-build-stack), or `macos-golden-gate` if none is set. See [Build stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md).

## After the build

Once a build finishes, you can:

- **Download the artifacts.** The CLI can save them directly with `--apk`, `--aab` (Android), `--ipa` (iOS), `--app` (iOS simulator), or `--zip` (web) — optionally followed by a file path. On Android, add `--form-factor` to pick the artifact of a Wear OS, Android TV, or Automotive module. In the Console, use the build's detail page. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).
- **Install it on a device.** Side-load the build onto a phone or tablet without the app store. See [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md).
- **Run it on an emulator or simulator.** Download, install and launch the build on a local Android emulator or iOS simulator with a single command. See [Run on an emulator or simulator](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md).
- **Share it with testers.** Send a public link so external testers can view and install the build without an account — pass `--share` to share automatically. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md).
- **Submit it to a store.** Pass `--destination` to send a native build to TestFlight or Google Play, or deploy a web build to a Live Update channel with `--channel`. See [App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md).

If a build fails, the logs tell you why — see [Monitor a build](https://capawesome.io/docs/cloud/native-builds/monitor-builds/index.md) and [Build Logs](https://capawesome.io/docs/cloud/native-builds/build-logs/index.md). For the full list of flags, see the [`apps:builds:create` reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate).

## Next steps

- [Monitor a build](https://capawesome.io/docs/cloud/native-builds/monitor-builds/index.md) — watch status and read logs.
- [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) — download and side-load the artifact.
- [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md) — give external testers a public link.
- [Automate builds in CI/CD](https://capawesome.io/docs/cloud/native-builds/integrations/index.md) — including the official [GitHub Action](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md).

# App Configuration

Capawesome Cloud allows you to optionally define your app configuration in a `capawesome.config.json` file for advanced use cases such as monorepos, subdirectory apps, or custom build commands. By default, Capawesome Cloud uses sensible defaults that work for standard project setups.

## Configuration File

The `capawesome.config.json` file should be placed in the root directory of your project. Below is an example configuration file:

```
{
    "cloud": {
        "apps": [
            {
                "appId": "4e837195-e8d8-4ad1-8705-7a32e18a98cf",
                "baseDir": "apps/my-app",
                "dependencyInstallCommand": "npm install",
                "webBuildCommand": "npm run build"
            }
        ]
    }
}
```

The following configuration options are available:

- `cloud.apps`: An array of app configurations.
- `appId`: The Capawesome Cloud App ID which can be found in the App Settings in Capawesome Cloud. This is required.
- `baseDir`: The base directory of your app within the repository. This is the directory that Capawesome Cloud uses to build the app from. All commands including `dependencyInstallCommand` and `webBuildCommand` are called from this location. If left unset, Capawesome Cloud defaults to the root of the Git repository.
- `dependencyInstallCommand`: The command to install dependencies for your app. Default is `npm ci` if a `package-lock.json` exists, otherwise `npm install`. Skipped automatically for native iOS/Android-only projects without a JavaScript toolchain.
- `webBuildCommand`: The command to build the web assets for your app. Default is `npm run build`. Skipped automatically for native iOS/Android-only projects without a JavaScript toolchain.

## Common setups

For step-by-step examples of the most common configurations, see:

- [Build from a monorepo](https://capawesome.io/docs/cloud/native-builds/monorepo/index.md) — monorepos and subdirectory apps (`baseDir`)
- [Use pnpm, Yarn, or bun](https://capawesome.io/docs/cloud/native-builds/package-managers/index.md) — alternative package managers (`dependencyInstallCommand`)
- [Configure the web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) — control which script builds your web assets (`webBuildCommand`)

# Custom iOS Provisioning Profiles for Multiple Targets

Capawesome Cloud automatically detects and applies provisioning profiles to all iOS targets based on their bundle identifiers. However, when working with multiple targets that use non-standard bundle ID patterns, you can manually configure the mapping between bundle IDs and target names.

## Automatic Provisioning Profile Detection

By default, Capawesome Cloud automatically:

1. Scans all provisioning profiles uploaded to your build
1. Matches profiles to targets based on bundle identifiers
1. Configures code signing for each target
1. Generates export options with the correct profile mappings

This automatic detection works seamlessly when your app extensions follow the standard iOS naming pattern where extension bundle IDs are prefixed with the main app bundle ID (e.g., `com.example.app` for the main app and `com.example.app.widget` for a widget extension).

## Configure Custom Mapping

To override the automatic detection for non-standard bundle ID patterns, set the `IOS_PROVISIONING_PROFILE_MAP` environment variable:

1. Navigate to the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page
1. Select your environment or create a new one
1. Add a variable named `IOS_PROVISIONING_PROFILE_MAP`
1. Set its value to a JSON object mapping bundle IDs to target names

JSON Format

The value must be a valid JSON object with bundle IDs as keys and target names as values. Ensure the target names match exactly as they appear in your Xcode project.

## Example

Consider a VPN app with the following targets:

- Main app: `com.example.vpnapp` (target: `App`)
- WireGuard extension: `com.example.wireguard` (target: `WireGuardExtension`)
- Packet tunnel: `com.example.tunnelprovider` (target: `PacketTunnel`)

To configure provisioning profiles for these targets:

1. Add an environment variable named `IOS_PROVISIONING_PROFILE_MAP`

1. Set its value to:

   ```
   {"com.example.wireguard":"WireGuardExtension","com.example.tunnelprovider":"PacketTunnel"}
   ```

1. Select this environment when triggering your build

The specified mappings will be used in addition to the automatic detection for the main app target.

# Environment Variables

This page lists the environment variables available during native builds. To set your own variables and secrets, see [Set Up Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md).

## Default variables

These are set automatically by Capawesome Cloud for every build and cannot be overridden. Use them in your build scripts to access information about the build context.

| Name                    | Type      | Description                                                                                                                                                                                     |
| ----------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CI`                    | `boolean` | Always `true` — indicates a CI environment.                                                                                                                                                     |
| `CI_APP_ID`             | `string`  | The ID of the application.                                                                                                                                                                      |
| `CI_BUILD_ID`           | `string`  | Unique identifier for the build.                                                                                                                                                                |
| `CI_BUILD_NUMBER`       | `string`  | Sequential number of the build.                                                                                                                                                                 |
| `CI_GIT_COMMIT_SHA`     | `string`  | The SHA of the Git commit.                                                                                                                                                                      |
| `CI_GIT_COMMIT_MESSAGE` | `string`  | The commit message.                                                                                                                                                                             |
| `CI_GIT_REFERENCE`      | `string`  | The Git branch or tag name.                                                                                                                                                                     |
| `CI_GIT_USERNAME`       | `string`  | The username for authenticated Git access to the linked repository (see [Git access](#git-access)). Not set when the repository is accessed without credentials.                                |
| `CI_GIT_PASSWORD`       | `string`  | The password or token for authenticated Git access to the linked repository (see [Git access](#git-access)). Masked in build logs. Not set when the repository is accessed without credentials. |
| `CI_PLATFORM`           | `string`  | The target platform (`ios` or `android`).                                                                                                                                                       |

## Git access

Git commands in your build scripts authenticate against the linked repository automatically. Capawesome Cloud clones only the commit being built and registers a Git credential helper that reads `CI_GIT_USERNAME` and `CI_GIT_PASSWORD`, so you can fetch what the shallow clone leaves out, for example tags for versioning:

```
git fetch --tags origin
git describe --tags
```

The credentials are those of the app's Git connection. For GitHub App connections, this is a temporary read-only installation token. The credential helper applies to Git commands inside the cloned repository.

To access other repositories, for example a private dependency, store a token as an [environment secret](https://capawesome.io/docs/cloud/native-builds/environments/index.md) and use it in your build script:

```
git clone "https://${GITHUB_TOKEN}@github.com/my-org/shared-module.git"
```

## Git LFS

Capawesome Cloud downloads [Git LFS](https://git-lfs.com/) files with the checkout of the commit being built. If your build doesn't need them, you can skip the download.

To skip all Git LFS files, set Git LFS's own `GIT_LFS_SKIP_SMUDGE` variable to `1` in a [custom environment](https://capawesome.io/docs/cloud/native-builds/environments/index.md) or as an ad-hoc variable. Environment variables are set before the repository is cloned, so the variable applies to the checkout.

To skip only some paths, add a comma-separated list of paths or glob patterns as `fetchexclude` to a `.lfsconfig` file in your repository:

```
[lfs]
    fetchexclude = design/**,videos/**
```

After the checkout, the build log shows how many Git LFS files were downloaded or skipped.

Pointer files

Skipped Git LFS files stay small pointer files in the build. Only skip files your build doesn't need.

## Reserved variables

These configure platform-specific build behavior. Set them in a [custom environment](https://capawesome.io/docs/cloud/native-builds/environments/index.md) or as ad-hoc variables.

| Name                           | Type     | Description                                                                                                                                                                                                                                                        |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ANDROID_BUILD_TYPE`           | `string` | The Android build type. Applies to every [application module](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).                                                                                                                               |
| `ANDROID_FLAVOR`               | `string` | The Android product flavor. Applies to every [application module](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).                                                                                                                           |
| `ANDROID_MODULES`              | `string` | Comma-separated Gradle project paths of the [application modules](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md) to collect (e.g. `:app,:wear`). Defaults to every application module. A listed module without an artifact fails the build. |
| `IOS_PROVISIONING_PROFILE_MAP` | `string` | JSON mapping bundle IDs to target names (see [Custom iOS provisioning profiles](https://capawesome.io/docs/cloud/native-builds/custom-ios-provisioning-profiles/index.md)).                                                                                        |
| `IOS_SCHEME`                   | `string` | The iOS scheme name.                                                                                                                                                                                                                                               |
| `NODE_VERSION`                 | `int`    | The Node.js major version (e.g. `22`, `24`, `26`).                                                                                                                                                                                                                 |
| `JAVA_VERSION`                 | `int`    | The Java major version (e.g. `17`, `21`).                                                                                                                                                                                                                          |
| `XCODE_VERSION`                | `int`    | The Xcode major version (e.g. `16`, `26`, `27`).                                                                                                                                                                                                                   |

Tool versions

The supported versions for Node.js, Java, and Xcode depend on your build stack — see [Build stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md).

# Set Up Environments

Environment variables let you customize your native builds by providing configuration values, secrets, and tool versions that are available during the build. Capawesome Cloud supports several kinds:

- **Default variables** — automatically set for every build (e.g. `CI`, `CI_BUILD_NUMBER`). You can't override them. See the [Environment variables](https://capawesome.io/docs/cloud/native-builds/environment-variables/index.md) reference.
- **Reserved variables** — platform and tool configuration you set, such as `JAVA_VERSION` or `ANDROID_BUILD_TYPE`. See the [Environment variables](https://capawesome.io/docs/cloud/native-builds/environment-variables/index.md) reference.
- **Custom environments** — named sets of variables and secrets for different scenarios (development, staging, production).
- **Ad-hoc variables** — temporary variables set when triggering a single build (not persisted).

A custom environment is the usual starting point. The flow is the same whether you use the CLI or the Console: **create an environment, add variables and secrets, then select it when you build.**

## Create a custom environment

A custom environment is a reusable, named set of variables and secrets you can select when triggering a build — for example separate environments for development, staging, and production.

Create an environment with the [`apps:environments:create`](https://capawesome.io/docs/cloud/cli/commands/#appsenvironmentscreate) command:

```
npx @capawesome/cli apps:environments:create --name production
```

Open the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page, click **Create environment**, and give it a name.

## Add variables and secrets

An environment holds two kinds of values:

- **Variables** store non-sensitive configuration such as API endpoints, feature flags, or version numbers.
- **Secrets** are encrypted values for sensitive data such as API keys, certificates, and passwords. They're encrypted at rest and in transit, and their values never appear in build logs.

Both are accessed the same way in your build scripts, using standard environment-variable syntax.

Add variables and secrets with the [`apps:environments:set`](https://capawesome.io/docs/cloud/cli/commands/#appsenvironmentsset) command. Pass `--variable` / `--secret` (repeatable), or import many at once from a `.env` file with `--variable-file` / `--secret-file`:

```
npx @capawesome/cli apps:environments:set \
  --name production \
  --variable API_URL=https://api.example.com \
  --secret API_KEY=sk_live_...
```

Remove values again with [`apps:environments:unset`](https://capawesome.io/docs/cloud/cli/commands/#appsenvironmentsunset).

On the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page, choose **Manage environment variables** or **Manage environment secrets** from the environment's actions menu, then add your values. Use **Delete** to remove one.

Bulk import

Use the **Import** feature to paste multiple `KEY=VALUE` pairs at once — the equivalent of the CLI's `--variable-file` / `--secret-file`.

Least privilege

Store credentials with the narrowest permissions your build actually needs — a read-only, single-purpose key instead of an account-wide one.

## Use an environment in a build

Environments are applied per build — you choose which one (if any) to use when you [trigger a build](https://capawesome.io/docs/cloud/native-builds/builds/index.md).

Pass `--environment` to [`apps:builds:create`](https://capawesome.io/docs/cloud/native-builds/builds/index.md):

```
npx @capawesome/cli apps:builds:create --platform android --git-ref main --environment production
```

In the **Build from Git** dialog, select your environment from the **Environment** dropdown before starting the build.

## Set a default environment

You can set a default environment that is preselected for every new build — useful when an environment always applies (for example, it holds a license key for a private npm package).

In the [Console](https://console.cloud.capawesome.io/), open your app's **Settings**, and in the **Builds** section enable the **Default environment** toggle, select the environment, and save.

## Ad-hoc variables

Need a value for just one build? Pass it as an **ad-hoc variable** when you trigger the build, without creating an environment — handy for testing a different tool version or [overwriting native project settings with Trapeze](https://capawesome.io/docs/cloud/native-builds/native-configurations/#advanced-trapeze):

```
npx @capawesome/cli apps:builds:create --platform android --git-ref main --variable JAVA_VERSION=21
```

Ad-hoc variables are **not encrypted** and may appear in build logs, so don't use them for secrets.

Reserved names

The variable `CI` and any variable starting with `CI_` are reserved and cannot be overridden.

Tool versions

The available versions for Node.js, Java, and Xcode depend on your build stack — see [Build stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md).

## Bonus: Video Walkthrough

For a detailed walkthrough with examples, see the blog post [Using Environment Variables and Secrets in Capawesome Cloud Builds](https://capawesome.io/blog/using-environment-variables-and-secrets-in-capawesome-cloud-builds/index.md).

# Estimate Usage

Native builds are billed by **build minutes**. This guide helps you estimate your monthly consumption so you can pick the right plan. For the hard limits, see [Limits & quotas](https://capawesome.io/docs/cloud/native-builds/limits/index.md).

## Estimate build minutes

```
Build minutes ≈ builds per month × average minutes per build
```

A few factors drive the average minutes per build:

- **Platform** — iOS builds are generally slower than Android.
- **Project size** — installing dependencies and building web assets takes longer for large projects.
- **Caching** — repeated builds of the same project are typically faster.

## Worked example

A team running **40** Android builds (~8 min each) and **40** iOS builds (~14 min each) per month:

```
(40 × 8) + (40 × 14) = 320 + 560 = 880 build minutes / month
```

## Reduce your usage

- Build only when needed — use [Automations](https://capawesome.io/docs/cloud/automations/index.md) to trigger builds on the right events rather than every push.
- Keep dependency installation lean to shorten each build.

# FAQ

## General

### Which frameworks are supported?

Native Builds works with Capacitor, Cordova, and native iOS and Android projects.

### Do I need a Mac to build for iOS?

No. iOS builds run on managed macOS build machines in the cloud, so you can build and sign iOS apps without a Mac. See [How builds work](https://capawesome.io/docs/cloud/native-builds/builds/index.md).

### Where do I configure my project (monorepo, package manager)?

In a `capawesome.config.json` file — see [Configuration file](https://capawesome.io/docs/cloud/native-builds/configuration/index.md), [Build from a monorepo](https://capawesome.io/docs/cloud/native-builds/monorepo/index.md), and [Use pnpm, Yarn, or bun](https://capawesome.io/docs/cloud/native-builds/package-managers/index.md).

## Signing

### Do I need a signing certificate?

Debug (Android) and Simulator (iOS) builds don't require signing. Any build you install on a real device or submit to a store must be signed. See [Certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md).

## Builds

### How are builds billed?

By build minutes — the time a build spends running. Only active build time counts; time spent queued while waiting for a machine doesn't. See [Limits & quotas](https://capawesome.io/docs/cloud/native-builds/limits/index.md) and [Estimate usage](https://capawesome.io/docs/cloud/native-builds/estimate-usage/index.md).

### What happens when I reach my monthly build-minute limit?

Any builds already running are allowed to finish — we never cancel a build mid-way. We'll notify you by email so you can upgrade your plan for more headroom. There are no metered overage charges.

### Are additional build minutes available?

Build minutes are included with your plan. To get more, upgrade to a higher plan — we don't sell separate build-minute packs. See the [pricing page](https://capawesome.io/pricing/).

### Is the concurrent build limit a hard limit? What happens when all slots are busy?

The number of builds that can run at the same time depends on your plan, but it's not a hard failure. When every slot is busy, additional builds are queued and start automatically as capacity frees up. Queue time doesn't count toward your build minutes.

### Can I see build usage per app?

Usage is tracked at the organization level. Per-app usage reporting is currently in private beta — [reach out to us](https://capawesome.io/docs/support/index.md) if you'd like access.

### Why did my build fail?

The fastest way to find out is [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md) on the failed build. See also [Troubleshooting](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md).

### How do I get the mapping.txt file for Google Play deobfuscation?

You don't need to. When you enable R8/ProGuard and publish your app as an Android App Bundle (AAB), the mapping file is embedded in the bundle and Google Play applies it automatically to deobfuscate crash and ANR reports. See [Publish Android App Bundles](https://capawesome.io/docs/cloud/native-builds/android-app-bundles/index.md).

### Can I build a Wear OS app?

Yes. Every Android build compiles all application modules of the project and returns an APK and AAB per module, including Wear OS, Android TV, and Automotive. See [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

### Can I build without connecting a Git repository?

Yes — build from local files with the CLI. See [Build without Git](https://capawesome.io/docs/cloud/native-builds/build-without-git/index.md).

### Can I share a build with testers who don't have an account?

Yes. Share a succeeded build via a public link and testers can view and install it without a Capawesome Cloud account. Build logs are never exposed, and you can revoke the link at any time. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md).

# Access Git Behind a Firewall

Capawesome Cloud [Native Builds](https://capawesome.io/docs/cloud/index.md) needs to clone your Git repository to run a build. If your Git server is behind a firewall, the build runner cannot reach it by default. This guide covers four approaches to solve this, each with different trade-offs for security, complexity, and maintenance.

## Reverse Tunnel (Recommended)

A reverse tunnel lets you expose your internal Git server to the internet without opening inbound firewall ports. You run a small daemon inside your network that establishes an outbound-only connection to a tunnel provider. The provider assigns a public hostname (e.g., `git-tunnel.yourcompany.com`) that routes traffic through the tunnel to your internal Git server.

This is the recommended approach for most teams because your firewall remains fully closed to inbound traffic while Native Builds can access your repository securely.

There are several tunnel providers available, such as [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/), [ngrok](https://ngrok.com/), or [Tailscale Funnel](https://tailscale.com/kb/1223/funnel). Refer to your chosen provider's documentation for setup instructions.

Once the tunnel is running, use the public hostname as the server URL when connecting Capawesome Cloud to your Git repository.

## Repository Mirroring

You can set up a mirror of your internal Git repository on a public Git hosting service like [GitHub](https://github.com/) or [GitLab](https://gitlab.com/). Native Builds then clones from the mirror instead of your internal server, so no direct access to your network is needed.

The most common approach is **push mirroring**, where your internal server pushes changes to the external mirror on a schedule. Some Git hosting services like GitLab offer [built-in mirroring](https://docs.gitlab.com/ee/user/project/repository/mirror/). For others, you can set up a cron job that runs `git push --mirror` to keep the mirror in sync.

Sync Delay

Mirrors are not real-time. There is always a delay between a push to your internal server and the mirror being updated. Make sure your mirroring schedule is frequent enough for your build workflow.

## IP Whitelisting

You can whitelist the IP ranges of the infrastructure providers that Capawesome Cloud uses to run Native Builds. This allows the build runners to access your internal Git server directly through your firewall.

### Required IP Ranges

You need to whitelist the IP ranges from the following providers:

- [Cloudflare](https://www.cloudflare.com/ips/)
- [Scaleway](https://www.scaleway.com/en/docs/account/reference-content/scaleway-network-information/)

Security Considerations

These IP ranges are shared across all customers of the respective providers. Whitelisting them allows any service hosted on those networks to reach your Git server, not just Capawesome Cloud. Make sure your Git server requires proper authentication (e.g., SSH keys or access tokens) in addition to the IP whitelist.

## Build without Git Connection

Instead of making your Git server accessible to Capawesome Cloud, you can bypass the Git connection entirely by uploading your local source files directly using the CLI's `--path` option. This approach avoids any firewall or networking configuration, but trades off Git integration features such as commit metadata in the Cloud UI, Automations, and the ability to trigger builds from the Console.

For details and usage instructions, see the [Build without Git Connection](https://capawesome.io/docs/cloud/native-builds/build-without-git/index.md) guide.

## Comparison

|                                 | Reverse Tunnel                  | Repository Mirroring                | IP Whitelisting              | Build without Git          |
| ------------------------------- | ------------------------------- | ----------------------------------- | ---------------------------- | -------------------------- |
| **Firewall changes**            | None                            | None                                | Inbound rules required       | None                       |
| **Security**                    | High (outbound-only, encrypted) | High (no exposure)                  | Low (broad shared IP ranges) | High (no network exposure) |
| **Real-time repository access** | Yes                             | No (sync delay)                     | Yes                          | N/A                        |
| **Complexity**                  | Medium                          | Low to medium                       | Low                          | Low                        |
| **Maintenance**                 | Low                             | Medium (sync schedule, credentials) | Medium (IP range updates)    | Low                        |
| **Git integration**             | Full                            | Full                                | Full                         | None                       |

# Build for Wear OS, Android TV and Automotive

An Android project can hold more than one application module: the phone app plus a Wear OS app, an Android TV app, or an Android Automotive app. Every Capawesome Cloud Android build compiles the whole Gradle project and collects the APK and the AAB of every application module it finds. Projects with a single application module are unchanged — they still produce one APK and one AAB.

Each artifact carries the form factor detected from its module's manifest. There is nothing to configure and nothing to enable.

To add a Wear OS module to a Capacitor project, see [How to Build a Wear OS App for Your Capacitor App](https://capawesome.io/blog/how-to-build-a-wear-os-app-for-your-capacitor-app/index.md). To exchange messages and state between the phone app and the watch app, use the [Capacitor Watch plugin](https://capawesome.io/docs/sdks/capacitor/watch/index.md).

## Prerequisites

Every application module in the project must:

- Use the same `applicationId` as the phone app. A [native configuration](https://capawesome.io/docs/cloud/native-builds/native-configurations/index.md) rewrites the `applicationId` in every module whose `build.gradle` (or `build.gradle.kts`) declares one, so declare it explicitly in each application module to keep them in sync.
- Use the same signing certificate. The build signs all modules with the keystore of the selected [Android signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md).
- Use a `versionCode` that is unique across form factors. Google Play rejects two artifacts of the same app with the same version code.
- Support the [build type](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) and product flavor of the build. `ANDROID_BUILD_TYPE` and `ANDROID_FLAVOR` apply to every application module, not just the phone app. A module without the selected build type or flavor is not built and not collected.
- Target a form factor of its own. The build fails when two application modules target the same form factor, such as a phone app and a demo app. Set the `ANDROID_MODULES` [environment variable](https://capawesome.io/docs/cloud/native-builds/environment-variables/#reserved-variables) to the Gradle project paths of the modules to collect, e.g. `:app,:wear`. The other modules are still compiled but not uploaded. A listed module without an artifact for the build type and flavor fails the build.
- Produce a single APK. With [APK splits](https://developer.android.com/build/configure-apk-splits) (e.g. ABI splits), set `universalApk true` so the build can pick the universal APK, which installs on every device. Without it, the build fails. App bundles are not affected.

### Unique version codes

Google Play applies two rules to version codes. A version code that has been uploaded once can never be used again for the same package, whatever the form factor. And each new release on a track must have a higher version code than the previous release on that track. The phone app and the watch app share the package name, so they need separate version codes, but neither has to be higher than the other: the mobile track only compares against earlier phone releases, the wear track against earlier watch releases.

The simplest scheme keeps the phone module on the build number from [Auto-increment build numbers](https://capawesome.io/docs/cloud/native-builds/auto-incrementing-build-numbers/index.md) and gives every other application module the build number plus a fixed offset in its own Gradle file:

```
android {
    defaultConfig {
        versionCode = (System.getenv("CI_BUILD_NUMBER") ?: "1").toInteger() + 1000000
    }
}
```

Choose the offset so the phone range can never reach it. With 1,000,000 per form factor, each range holds a million builds and stays far below Google Play's limit of 2,100,000,000.

## Form factors

The form factor comes from the features the module's manifest declares as required (`android:required="true"`, the default):

| Form factor  | Required feature                   | Typical module                 |
| ------------ | ---------------------------------- | ------------------------------ |
| `mobile`     | none of the features below         | Phone and tablet app (default) |
| `watch`      | `android.hardware.type.watch`      | Wear OS app                    |
| `tv`         | `android.software.leanback`        | Android TV app                 |
| `automotive` | `android.hardware.type.automotive` | Android Automotive OS app      |

A feature declared with `android:required="false"` does not count, so a phone app that optionally supports Android TV stays `mobile`.

When no form factor is requested, artifacts are selected in the order `mobile`, `watch`, `tv`, `automotive`. The same order decides which artifact supplies the package name and version shown for the build in the Console.

## Download the artifacts

[`apps:builds:download`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsdownload) and [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) accept `--form-factor` with the values `mobile`, `watch`, `tv`, and `automotive`. It picks which Android artifact the `--apk` and `--aab` flags download — it never changes what is built.

```
# Mobile AAB, saved as <buildId>.aab
npx @capawesome/cli apps:builds:download --aab

# Watch AAB of the same build, saved as <buildId>-watch.aab
npx @capawesome/cli apps:builds:download --aab --form-factor watch
```

Without `--form-factor`, the CLI downloads the first artifact in the order `mobile`, `watch`, `tv`, `automotive`, so a project with a phone module gets the phone artifact. A mobile artifact is saved as `<buildId>.<type>`, other form factors as `<buildId>-<formFactor>.<type>`, unless you pass a file path. Each flag downloads one artifact per invocation, so two form factors take two commands.

Open the build's detail page from the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page. It lists every artifact of the build with its form factor, and each artifact has its own download.

[`apps:builds:run`](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md) selects its artifact the same way. The **Install** button and its QR code always serve the mobile artifact, as does the public [share page](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md); a build without a mobile artifact shows no Install or Download button.

## Publish to Google Play

A submission to a [Google Play destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/index.md) uploads every artifact of the destination's publishing format (AAB or APK), mobile first. The destination's track applies to the mobile artifact. The other artifacts go to Google Play's prefixed track of the same name:

| Form factor  | Track on Google Play                               |
| ------------ | -------------------------------------------------- |
| `mobile`     | the destination's track, e.g. `production`         |
| `watch`      | `wear:<track>`, e.g. `wear:production`             |
| `tv`         | `tv:<track>`, e.g. `tv:production`                 |
| `automotive` | `automotive:<track>`, e.g. `automotive:production` |

Before the first submission, enable the form factor in Google Play Console under **Advanced settings → Form factors**. Google Play only offers the prefixed tracks after this opt-in, and Wear OS apps go through their own review.

When a build has more than one artifact, Capawesome Cloud validates all of them against Google Play before it publishes anything. A missing `wear:production` track therefore fails the submission before the phone app is released. See [Submit a build](https://capawesome.io/docs/cloud/app-store-publishing/submit-a-build/index.md).

[Huawei AppGallery](https://capawesome.io/docs/cloud/app-store-publishing/destinations/huawei-appgallery/index.md) and [Firebase App Distribution](https://capawesome.io/docs/cloud/app-store-publishing/destinations/firebase-app-distribution/index.md) destinations upload only the mobile artifact.

## Limitations

- **iOS**: standalone watchOS, tvOS, and visionOS apps are not built as separate artifacts. iOS targets and app extensions ship inside the single `.ipa` and are configured through [custom iOS provisioning profiles](https://capawesome.io/docs/cloud/native-builds/custom-ios-provisioning-profiles/index.md).
- **Android XR**: an Android XR module is not detected and is treated as `mobile`.
- **No override**: the form factor comes from the manifest. There is no per-module setting to change it.
- **APK splits**: only the universal APK is collected, not the per-ABI or per-density APKs.
- **Install on a device**: a watch APK cannot be installed through the Install button or the QR code. Download it with `--form-factor watch` and install it with `adb install`.

## Next steps

- [Publish Android App Bundles](https://capawesome.io/docs/cloud/native-builds/android-app-bundles/index.md) — the format Google Play requires for new apps.
- [Set up signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md) — the keystore that signs every module.
- [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md) — give external testers a public link to the mobile artifact.

# Install on a Device

With [Capawesome Cloud](/) you can install a build directly on a physical device — no app store required — by scanning a QR code or tapping a download link, similar to platforms like Loadly or Diawi.

After a build completes, open its detail page and click **Install** to get the QR code and download link. The exact requirements differ by platform.

## Android

Create an Android build (**Debug** for quick testing, or **Release** which requires a [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md)). Then, to install an APK from outside the Play Store, allow installations from unknown sources:

1. Open **Settings → Apps → Special app access → Install unknown apps**.
1. Select the app you'll use to download the APK (e.g. **Chrome**).
1. Enable **Allow from this source**.

The exact path varies by manufacturer (on Samsung: **Settings → Biometrics and security → Install unknown apps**).

Open **Settings → Security** and enable **Unknown sources**.

Then open the build's detail page, click **Install**, scan the QR code (or tap **Download** on the device), and open the downloaded APK to install.

Google Play Protect

Play Protect may warn that the app is from an unknown developer. You can dismiss the warning to proceed — this is normal for side-loaded apps.

**Install** and the QR code always serve the phone APK. To install the APK of a [Wear OS, Android TV, or Automotive module](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md), download it with `--form-factor watch` (or `tv`, `automotive`) and install it with `adb install`.

## iOS

Installing an iOS build on a device requires a **signed build** whose provisioning profile includes the device.

1. **Register the device.** Find your device's UDID (you can use the [iOS UDID Finder](https://capawesome.io/tools/ios-udid-finder/)) and add it to your Apple Developer account, then include it in the provisioning profile used for the build. See [iOS Signing Certificates](https://capawesome.io/docs/cloud/native-builds/certificates/ios/index.md).
1. **Create a signed build.** Trigger an iOS build with the **Development** or **Ad Hoc** [build type](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) and the matching [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/ios/index.md) and provisioning profile. (A **Simulator** build only [runs in the iOS Simulator](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md), not on a device.)
1. **Install.** Open the build's detail page, click **Install**, and scan the QR code with the registered device or tap **Download** on the device to install.

## Next steps

- [Run on an emulator or simulator](https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/index.md) — test a build locally without a physical device.
- [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md) — give external testers a public link to install the build without an account.
- [Build types](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) — which type to pick for testing vs distribution.
- [Submit to the App Store or Play Store](https://capawesome.io/docs/cloud/app-store-publishing/index.md) — for store distribution instead of side-loading.

# Limits & Quotas

This page summarizes the limits that apply to Native Builds. Plan-specific allowances are listed on the [pricing page](https://capawesome.io/pricing/).

## Build minutes

Native builds are billed by **build minutes** — the time a build spends running. Only active build time counts; time spent queued while waiting for a machine doesn't. [App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md) deployment jobs count toward build minutes as well, including the time spent waiting for App Store Connect to process a build. Your plan includes a number of build minutes per month. Builds already running when you reach the limit are allowed to finish; to get more headroom, upgrade your plan — there are no metered overage charges. See [Estimate usage](https://capawesome.io/docs/cloud/native-builds/estimate-usage/index.md) to predict your consumption.

## Concurrency

The number of builds that can run at the same time depends on your plan. Additional builds are queued and start as capacity frees up.

## Build timeout

Each build has a maximum duration. A build that exceeds it is stopped and marked as failed.

## Artifact retention

Build artifacts (APK, AAB, IPA) are retained for a limited time, after which they're removed. Download or [submit](https://capawesome.io/docs/cloud/app-store-publishing/index.md) artifacts you want to keep.

## Related

- [Estimate usage](https://capawesome.io/docs/cloud/native-builds/estimate-usage/index.md) — predict build-minute consumption.
- [Pricing](https://capawesome.io/pricing/) — plan-specific allowances.

# Monitor a Build

After you [trigger a build](https://capawesome.io/docs/cloud/native-builds/builds/index.md), you can follow its progress, read its logs, download the result, and cancel it if needed — from the [CLI](https://capawesome.io/docs/cloud/cli/index.md) or the [Console](https://console.cloud.capawesome.io).

Every build moves through a handful of states: **queued** (waiting for a free runner), **pending** (a runner has been assigned and is picking up the job), **in progress** (building), and then a final **succeeded**, **failed**, or **canceled**.

## Track build status

List recent builds, or fetch a single build to check its current status:

```
npx @capawesome/cli apps:builds:list
npx @capawesome/cli apps:builds:get
```

`apps:builds:list` accepts `--platform` to filter by `android`, `ios`, or `web`, and `--limit`/`--offset` to page through results. Add `--json` to either command to get machine-readable output — including the related job's status and timing, which is useful in scripts.

Open the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page to see all builds and their status at a glance. Click a build to open its detail page, where the status updates live while it runs.

## Read the logs

The logs are the fastest way to understand what a build is doing — and why it failed.

Stream the logs of an ongoing build, or print them for a completed one:

```
npx @capawesome/cli apps:builds:logs
```

Open the build's detail page to follow the logs live and review them again after the build finishes.

See [Build logs](https://capawesome.io/docs/cloud/native-builds/build-logs/index.md) for more. If a build failed, the quickest way to understand why is [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md), or work through [Troubleshooting](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md).

## Download the artifacts

Once a build succeeds, grab its artifacts — an `.apk` and `.aab` per Android application module, an `.ipa` for iOS, or a `.zip` of web assets.

Use [`apps:builds:download`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsdownload) with the flag for the artifact you want — optionally followed by a file path. On Android, `--form-factor` picks the application module:

```
npx @capawesome/cli apps:builds:download --apk ./app.apk
npx @capawesome/cli apps:builds:download --apk --form-factor watch
```

Open the build's detail page and download the artifact directly, or click **Install** to side-load it onto a device. Android builds list every artifact with its form factor.

To install a build on a physical device, see [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md). For builds with a Wear OS, Android TV, or Automotive module, see [Build for Wear OS, Android TV and Automotive](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md).

## Cancel a build

Need to stop a queued or running build? Cancel it to free up your build minutes.

```
npx @capawesome/cli apps:builds:cancel
```

Open the running build's detail page and click **Cancel**.

## Next steps

- [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) — download and side-load the artifact.
- [Build logs](https://capawesome.io/docs/cloud/native-builds/build-logs/index.md) — read and interpret your build output.
- [Troubleshooting](https://capawesome.io/docs/cloud/native-builds/troubleshooting/index.md) — fix a failing build.

# Build from a Monorepo

Capawesome Cloud builds standard projects out of the box, but plenty of teams keep their app in a subdirectory or alongside other packages in a monorepo. For those setups, you tell Capawesome Cloud where each app lives with a [`capawesome.config.json`](https://capawesome.io/docs/cloud/native-builds/configuration/index.md) file.

The key option is `baseDir` — the directory Capawesome Cloud treats as the app's root. Every command runs from there, including `dependencyInstallCommand` and `webBuildCommand`. If you leave it unset, the Cloud builds from the root of the repository.

The config file always sits at the repository root

`capawesome.config.json` belongs in the **root** of your Git repository, even when your apps live in subdirectories. `baseDir` paths are resolved relative to that root.

## App in a subdirectory

If your app isn't at the repository root, point `baseDir` at it. You can list several apps from the same repository — each entry maps one directory to one Capawesome Cloud App ID:

```
├─ apps/
│  ├─ my-app1/
│  └─ my-app2/
└─ capawesome.config.json
```

capawesome.config.json

```
{
    "cloud": {
        "apps": [
            {
                "appId": "your-app-id-1",
                "baseDir": "apps/my-app1"
            },
            {
                "appId": "your-app-id-2",
                "baseDir": "apps/my-app2"
            }
        ]
    }
}
```

With just `baseDir` set, the Cloud installs dependencies and builds web assets from inside that directory — which is exactly what you want when each app manages its own `package.json` and lockfile.

## Monorepo with shared dependencies

In a workspace monorepo (npm/pnpm/Yarn workspaces), dependencies are usually installed once at the workspace root rather than per app. Because every command runs from `baseDir`, you need to step back up to the root to install and build.

Keep in mind that `dependencyInstallCommand` and `webBuildCommand` run from `baseDir`, so a relative `cd` is the simplest way to reach the workspace root — adjust the number of `../` segments to match how deep your app is nested:

capawesome.config.json

```
{
    "cloud": {
        "apps": [
            {
                "appId": "your-app-id-1",
                "baseDir": "packages/app1",
                "dependencyInstallCommand": "cd ../.. && npm install",
                "webBuildCommand": "cd ../.. && npm run build --workspace=app1"
            },
            {
                "appId": "your-app-id-2",
                "baseDir": "packages/app2",
                "dependencyInstallCommand": "cd ../.. && npm install",
                "webBuildCommand": "cd ../.. && npm run build --workspace=app2"
            }
        ]
    }
}
```

Here `packages/app1` is two levels below the root, so `cd ../..` lands at the workspace root, where the install and the workspace-scoped build run. The native part of the build still happens in `baseDir`, where your Capacitor/Cordova project and its `android`/`ios` folders live.

## Next steps

- [App Configuration](https://capawesome.io/docs/cloud/native-builds/configuration/index.md) — the full `capawesome.config.json` schema.
- [Use pnpm, Yarn, or bun](https://capawesome.io/docs/cloud/native-builds/package-managers/index.md) — for workspaces managed by pnpm or Yarn.
- [Configure the web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) — control which script builds your web assets.

# Set Up Native Configurations

A **native configuration** is a named, per-app record that Capawesome Cloud applies to your native project right before a build starts. Instead of committing a different app name or package name for every variant of your app, you keep one project and pick the native configuration you want at build time.

Every native configuration has a name and two optional fields:

| Field            | Description                                                                             |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Display name** | The app name that is displayed on the home screen.                                      |
| **Package name** | The unique identifier of the app — the application ID on Android, the bundle ID on iOS. |

Both fields are optional. A field you leave empty is left untouched in the native project, so a native configuration can change just the name, just the identifier, or both.

This is the usual setup for white-label apps that ship the same code base under different brands, and for development, staging, and production variants that need to live side by side on the same device.

Android and iOS only

Native configurations apply to native projects. A web build ignores the app's default native configuration, and selecting one explicitly is rejected.

## Create a native configuration

Create a native configuration with the [`apps:configurations:create`](https://capawesome.io/docs/cloud/cli/commands/#appsconfigurationscreate) command:

```
npx @capawesome/cli apps:configurations:create \
  --name staging \
  --display-name "My App (Staging)" \
  --package-name com.example.app.staging
```

Use [`apps:configurations:list`](https://capawesome.io/docs/cloud/cli/commands/#appsconfigurationslist) and [`apps:configurations:get`](https://capawesome.io/docs/cloud/cli/commands/#appsconfigurationsget) to inspect what you have, [`apps:configurations:update`](https://capawesome.io/docs/cloud/cli/commands/#appsconfigurationsupdate) to change a value, and [`apps:configurations:delete`](https://capawesome.io/docs/cloud/cli/commands/#appsconfigurationsdelete) to remove one.

Pass an empty string to clear a value again — with `--display-name ""`, the app name in your project is left untouched from then on.

Open the [Native configurations](https://console.cloud.capawesome.io/apps/_/configurations) page in the **Build** section of your app, click **Create native configuration**, and enter a name plus the values you want to apply.

Names are unique per app and compared case-insensitively, so `Staging` and `staging` are the same name.

## Use a native configuration in a build

Pass `--configuration` to [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate):

```
npx @capawesome/cli apps:builds:create \
  --platform ios \
  --git-ref main \
  --type app-store \
  --configuration staging
```

In the **Build from Git** dialog, select the native configuration from the **Native configuration** dropdown before starting the build.

## Set a default native configuration

You can set a default native configuration that applies to every build that doesn't select one — useful when one identity is the normal case and the others are exceptions.

In the [Console](https://console.cloud.capawesome.io/), open your app's **Settings**, and in the **Builds** section enable the **Default native configuration** toggle, select the native configuration, and save.

Capawesome Cloud resolves the native configuration for a build in this order:

1. The native configuration selected for the build.
1. The app's default native configuration.
1. None — the native project is built exactly as it is committed.

An [automation](https://capawesome.io/docs/cloud/automations/index.md) can carry a native configuration of its own, which is used for every build it triggers. The app's default is **not** applied to automation-triggered builds, so an automation without a native configuration always builds the project as committed.

## How native configurations are applied

Native configurations are applied after the dependencies are installed and before the [web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) runs and the platform is synced. Only the values you set are written — everything else in your project is left alone.

### Android

The rewrite runs in every module whose `build.gradle` (or `build.gradle.kts`) declares an `applicationId`, because Google Play requires one package name across [form factors](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md). In each of these modules, it rewrites:

- `applicationId` in `<module>/build.gradle` (or `<module>/build.gradle.kts`)
- The string resources `app_name` and `title_activity_main` in `<module>/src/main/res/values/strings.xml`
- The string resources `package_name` and `custom_url_scheme` in the same file — but only while they still hold the previous application ID, so a deliberately customized URL scheme is preserved

A module that relies on the `namespace` as its application ID is not rewritten. The `namespace` itself stays untouched.

Firebase and google-services.json

If your project uses `google-services.json`, it must contain a client entry for the new `applicationId` — otherwise the Google Services Gradle plugin fails the build with `No matching client found for package name`. Add an app with the new package name to your Firebase project and commit the regenerated file. A single `google-services.json` can hold the client entries of all your variants.

### iOS

- `PRODUCT_BUNDLE_IDENTIFIER` in `App.xcodeproj/project.pbxproj`
- `CFBundleDisplayName` in the `Info.plist` of the main app target

The bundle identifier is substituted as a prefix across all targets, so app extensions keep their suffix: with a main target moving from `com.example.app` to `com.example.staging`, `com.example.app.ShareExtension` becomes `com.example.staging.ShareExtension`.

Provisioning profiles must match the new bundle ID

A signed iOS build needs a provisioning profile for the **new** bundle identifier. If the profile you build with is still tied to the old one, the build fails during code signing. Register the new identifier in the Apple Developer portal, create a matching profile, and upload it to the [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/ios/index.md) you use for the build.

### Cordova

In a Cordova project, the values are written to `config.xml` instead of the platform projects:

- The `id` attribute of the `<widget>` element
- The `<name>` element

`cordova prepare` then propagates both values into the Android and iOS platform projects.

## Advanced: Trapeze

Native configurations cover the two settings that change most often. For everything else — version names, entitlements, or arbitrary edits to `Info.plist`, `build.gradle`, and `AndroidManifest.xml` — use [Trapeze](https://trapeze.dev/), a mobile app configuration tool that you run yourself as part of the build.

Trapeze runs in your [web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md), which executes after the native configuration has been applied. If both change the same value, the Trapeze value wins.

### Installation

First, install Trapeze as a development dependency in your project:

```
npm install --save-dev @trapezedev/configure
```

### Configuration File

Create a configuration file named `capawesome.yml` in the root of your project. This file defines the native project settings you want to overwrite.

Here's a basic example that modifies the App ID and display name:

```
platforms:
  android:
    packageName: com.example.myapp
    appName: My App
  ios:
    bundleId: com.example.myapp
    displayName: My App
```

Platform-specific settings

Trapeze uses platform-specific keys for similar settings. For example, Android uses `packageName` while iOS uses `bundleId`. Refer to the [Android](https://trapeze.dev/docs/Operations/android) and [iOS](https://trapeze.dev/docs/Operations/ios) operation guides for complete lists of available settings.

### Build Script

Add an npm script to your `package.json` that runs Trapeze for Android and iOS platforms before the web build process:

```
{
  "scripts": {
    "capawesome:build": "if [ \"$CI_PLATFORM\" = \"ios\" ] || [ \"$CI_PLATFORM\" = \"android\" ]; then npx trapeze run capawesome.yml -y --$CI_PLATFORM; fi && npm run build"
  }
}
```

Capawesome Cloud automatically calls the [web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) during the build process. The script conditionally runs Trapeze only for iOS and Android platforms using the `$CI_PLATFORM` environment variable.

### Using Environment Variables

You can use Capawesome Cloud's [environment variables](https://capawesome.io/docs/cloud/native-builds/environments/index.md) to dynamically configure your native projects. This is particularly useful for overwriting settings based on your build environment.

#### Define Variables

First, define variables in your Trapeze configuration file:

```
vars:
  APP_ID:
  APP_NAME:

platforms:
  android:
    packageName: $APP_ID
    appName: $APP_NAME
  ios:
    bundleId: $APP_ID
    displayName: $APP_NAME
```

#### Set Variable Values

Then, set the variable values in your Capawesome Cloud environment:

1. Navigate to the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page
1. Select your environment or create a new one
1. Add variables with their values:
1. `APP_ID`: `com.example.myapp`
1. `APP_NAME`: `My App`

You can create multiple environments with different values (e.g., development, staging, production) and select the appropriate environment when triggering a build.

Default values

You can provide default values for variables that will be used if no environment variable is set:

```
vars:
  APP_ID:
    default: com.example.default
  APP_NAME:
    default: Default App Name
```

## Next steps

- [Trigger a build](https://capawesome.io/docs/cloud/native-builds/builds/index.md) — select a native configuration when you start a build.
- [Set up environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md) — the variables and secrets available during a build.
- [Auto-increment build numbers](https://capawesome.io/docs/cloud/native-builds/auto-incrementing-build-numbers/index.md) — keep version codes and build numbers unique.
- [API](https://capawesome.io/docs/cloud/api/index.md) — manage native configurations programmatically at `/v1/apps/{appId}/configurations`.

# Install Private npm Packages

You can use private npm packages within your [Capawesome Cloud](/) native builds by configuring a custom npm registry. This guide shows you how to set up authentication to access private packages from any npm registry provider.

## Add Environment Secret

To access private npm packages, you need to configure an authentication token:

1. Obtain your authentication token from your npm registry provider
1. Add it to your Capawesome Cloud app as an environment secret with an appropriate name (e.g., `NPM_REGISTRY_TOKEN`) as described in [Add variables and secrets](https://capawesome.io/docs/cloud/native-builds/environments/#add-variables-and-secrets)

Keep your tokens secure

Never commit authentication tokens directly to your repository. Always use environment secrets to store sensitive information like authentication tokens.

## Configure npm Registry

Create a new file named `.npmrc` in the root of your project with the following configuration:

```
@your-scope:registry=https://your-registry.example.com
//your-registry.example.com/:_authToken=${YOUR_NPM_REGISTRY_TOKEN}
```

Replace the following placeholders:

- `@your-scope`: Your package scope (e.g., `@mycompany`)
- `https://your-registry.example.com`: Your npm registry URL
- `${YOUR_NPM_REGISTRY_TOKEN}`: The name of your environment secret containing the authentication token

This configuration tells npm to use your custom registry for packages under your scope and authenticate using the environment secret.

Capawesome Insiders

If you're looking to install private Capawesome Insiders npm packages, refer to the [Integrate Capawesome Insiders with Capawesome Cloud](https://capawesome.io/docs/insiders/integrations/capawesome-cloud/index.md) guide for specific setup instructions.

## Manage Multiple Environments

If your local development environment stops working with the new `.npmrc` file, you can create a separate configuration file specifically for Capawesome Cloud:

1. Create a new file named `.npmrc.capawesome` in the root of your project with the registry configuration
1. On the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page, choose **Manage environment variables** from your environment's actions menu
1. Add a new environment variable named `NPM_CONFIG_USERCONFIG`
1. Set its value to `/tmp/capawesome/repo/.npmrc.capawesome`

Custom file location

If your `.npmrc.capawesome` file is not in your project's root directory, adjust the path in the `NPM_CONFIG_USERCONFIG` environment variable accordingly.

This approach allows you to maintain separate npm configurations for local development and Capawesome Cloud builds.

# Override Java Version on Android Builds

Capawesome Cloud automatically detects the Android Gradle Plugin version used in your project and applies the corresponding Java version. However, you can manually override the Java version if needed.

## Automatic Java Version Detection

Capawesome Cloud supports Gradle Plugin Version 8.0.0 and higher. The Java version is automatically selected based on your Android Gradle Plugin version:

| Android Gradle Plugin | Java Version |
| --------------------- | ------------ |
| 8.0.0 - 8.7.1         | 17           |
| >= 8.7.2              | 21           |

This automatic detection ensures your builds use the appropriate Java version without additional configuration.

## Override Java Version

To override the automatic Java version selection, set the `JAVA_VERSION` environment variable:

1. Navigate to the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page
1. Select your environment or create a new one
1. Add a variable named `JAVA_VERSION`
1. Set its value to the major version number (e.g., `17` or `21`)

Version constraints

The `JAVA_VERSION` environment variable must be set to an integer representing the major version, such as `17` or `21`. For available Java versions, refer to the [Build Stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md) documentation.

## Example

To use Java 17 for your Android builds regardless of your Gradle Plugin version:

1. Add an environment variable named `JAVA_VERSION` with the value `17`
1. Select this environment when triggering your build

The specified Java version will be used instead of the automatically detected version.

# Use pnpm, Yarn, or bun

By default, Capawesome Cloud installs dependencies with `npm ci` (or `npm install` if there is no `package-lock.json`) and builds web assets with `npm run build`. If your project uses pnpm or Yarn instead, override these two steps with the `dependencyInstallCommand` and `webBuildCommand` options in a [`capawesome.config.json`](https://capawesome.io/docs/cloud/native-builds/configuration/index.md) file.

The [build environment](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md) already ships with Node.js, npm, pnpm, Yarn, and bun — so there's no need to install your package manager first. Just call it directly.

Don't reinstall a pre-installed package manager

Reaching for `npm install -g pnpm` breaks the build, because the binary already exists:

```
npm error code EEXIST
npm error path .../bin/pnpm
npm error EEXIST: file already exists
```

## pnpm

Install dependencies and build with pnpm:

capawesome.config.json

```
{
    "cloud": {
        "apps": [
            {
                "appId": "your-app-id",
                "dependencyInstallCommand": "pnpm install --frozen-lockfile",
                "webBuildCommand": "pnpm build"
            }
        ]
    }
}
```

## Yarn

The same approach works for Yarn:

capawesome.config.json

```
{
    "cloud": {
        "apps": [
            {
                "appId": "your-app-id",
                "dependencyInstallCommand": "yarn install --immutable",
                "webBuildCommand": "yarn build"
            }
        ]
    }
}
```

## bun

bun works the same way — install dependencies and build:

capawesome.config.json

```
{
    "cloud": {
        "apps": [
            {
                "appId": "your-app-id",
                "dependencyInstallCommand": "bun install --frozen-lockfile",
                "webBuildCommand": "bun run build"
            }
        ]
    }
}
```

## Pin the version with Corepack

The pre-installed pnpm and Yarn versions can drift from the version your team uses locally. To lock the build to a specific version, add a `packageManager` field to your `package.json`:

package.json

```
{
    "packageManager": "pnpm@9.12.0"
}
```

[Corepack](https://nodejs.org/api/corepack.html) is already enabled in the build environment, so your existing `pnpm install` command automatically picks up the version declared here — no change to `capawesome.config.json` needed.

Install from the lockfile

The examples above use `--frozen-lockfile` (pnpm) and `--immutable` (Yarn) so the Cloud installs the exact versions in your lockfile and fails if it's out of date — the same reproducibility you'd want in any CI pipeline.

## Next steps

- [App Configuration](https://capawesome.io/docs/cloud/native-builds/configuration/index.md) — the full `capawesome.config.json` schema.
- [Build from a monorepo](https://capawesome.io/docs/cloud/native-builds/monorepo/index.md) — for pnpm or Yarn workspaces.
- [Configure the web build script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) — control which script builds your web assets.

# Run on an Emulator or Simulator

Run a completed build on a local Android emulator or iOS simulator without downloading and installing it by hand. The [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) downloads the build artifact, starts the target device, installs the app and launches it.

Booting an emulator or simulator requires a local process, so this is a CLI-only workflow. The Console shows you the command to copy.

## Requirements

| Platform | Build type               | Requirements                                 |
| -------- | ------------------------ | -------------------------------------------- |
| Android  | **Debug** or **Release** | Android SDK with at least one emulator (AVD) |
| iOS      | **Simulator** only       | macOS with Xcode and at least one simulator  |

iOS builds of the type **Development**, **Ad Hoc**, **App Store** or **Enterprise** are signed for physical devices and cannot run in the simulator. See [Install on a Device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) for those, and [Build Types](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) for an overview of all types.

The CLI looks for the Android SDK in the `ANDROID_HOME` or `ANDROID_SDK_ROOT` environment variable and falls back to the default installation directory. On Android it installs the first artifact in the order `mobile`, `watch`, `tv`, `automotive` of the [form factors](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md), so a project with a phone module runs the phone app.

## Run a build

```
npx @capawesome/cli apps:builds:run --app-id <app-id> --build-number 42
```

Without options, the CLI asks which app, build and target device to use.

Open the build's detail page and click **Run**. The dialog shows the command for that build — copy it and run it in your terminal.

## Choose a target device

By default the CLI asks which target device to use. Devices that are already running are listed first, so you can reuse a running emulator or simulator instead of waiting for one to boot.

Select a target device without the prompt:

```
# By ID (AVD ID on Android, UDID on iOS)
npx @capawesome/cli apps:builds:run --build-number 42 --target Pixel_8_Pro

# By name
npx @capawesome/cli apps:builds:run --build-number 42 --target-name "iPhone 17 Pro"

# By name, when several target devices share it
npx @capawesome/cli apps:builds:run --build-number 42 \
  --target-name "iPhone 17 Pro" --target-name-sdk-version 26.5
```

Non-interactive environments

In CI or any other non-interactive shell, pass the app, build and target device explicitly. The CLI cannot prompt and exits with an error otherwise.

## Next steps

- [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) — run a build on physical hardware instead.
- [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md) — give external testers a link to install the build.
- [`apps:builds:run` reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsrun) — every option for running a build from the CLI.
- [Capawesome CLI 4.18.0 Release](https://capawesome.io/blog/capawesome-cli-4-18-0-release/index.md) — the release this command shipped in.

# Sample Projects

The following sample projects demonstrate how to build iOS and Android apps in the cloud with [Capawesome Cloud](/) Native Builds. Each repository contains a ready-to-use GitHub Actions workflow that triggers a cloud build on every push using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).

Fork any of these repositories to try Capawesome Cloud with a working setup in minutes.

## Capacitor

- [**cloud-capacitor-cocoapods-demo**](https://github.com/capawesome-team/cloud-capacitor-cocoapods-demo) — Capacitor app using [CocoaPods](https://cocoapods.org/) for iOS dependencies.
- [**cloud-capacitor-spm-demo**](https://github.com/capawesome-team/cloud-capacitor-spm-demo) — Capacitor app using [Swift Package Manager](https://www.swift.org/documentation/package-manager/) for iOS dependencies.
- [**cloud-capacitor-pnpm-demo**](https://github.com/capawesome-team/cloud-capacitor-pnpm-demo) — Capacitor app managed with the [pnpm](https://pnpm.io/) package manager.
- [**cloud-nx-demo**](https://github.com/capawesome-team/cloud-nx-demo) — Capacitor app inside an [Nx](https://nx.dev/) monorepo, configured via a custom [`capawesome.config.json`](https://capawesome.io/docs/cloud/native-builds/configuration/index.md).

## Cordova

- [**cloud-cordova-demo**](https://github.com/capawesome-team/cloud-cordova-demo) — Plain [Apache Cordova](https://cordova.apache.org/) app.
- [**cloud-cordova-ionic-demo**](https://github.com/capawesome-team/cloud-cordova-ionic-demo) — Apache Cordova app with [Ionic Framework](https://ionicframework.com/) and [Angular](https://angular.dev/).

## Native

- [**cloud-android-kotlin-demo**](https://github.com/capawesome-team/cloud-android-kotlin-demo) — Native [Android](https://developer.android.com/) app written in [Kotlin](https://kotlinlang.org/).
- [**cloud-ios-swift-demo**](https://github.com/capawesome-team/cloud-ios-swift-demo) — Native [iOS](https://developer.apple.com/ios/) app written in [Swift](https://www.swift.org/).

## Suggest a Sample

Missing a setup you would like to see? [Get in touch](/contact/) and we will consider adding it.

# Getting Started

In this guide, you will learn how to create your first native build using Capawesome Cloud Native Builds.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
- An iOS or Android app in a Git repository (Capacitor, Cordova, or native).
- The latest version of the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) installed and [authenticated](https://capawesome.io/docs/cloud/cli/authentication/index.md).

## Step 1: Create an App

To identify your app in Capawesome Cloud, you need to create an app in the console. If you have already created an app, you can **skip this step** and proceed to Step 2.

To create an app using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), use the [`apps:create`](https://capawesome.io/docs/cloud/cli/commands/#appscreate) command:

```
npx @capawesome/cli apps:create
```

You will be prompted to select the organization you want to create the app in and to provide a name for the app. The CLI will then create the app.

To create an app using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/apps), select the organization you want to create the app in and click on the "Create app" button.

\[

\](/docs/assets/videos/cloud-app-create.mp4)

## Step 2: Connect Your Source Code

The most common way to build is by connecting your Git repository to Capawesome Cloud. This lets the build service clone your source code and build your app, and unlocks Git metadata and [Automations](https://capawesome.io/docs/cloud/automations/index.md).

Follow these steps to connect your repository:

1. Create a [Git connection](https://capawesome.io/docs/cloud/integrations/index.md) for your organization on the [Git connections](https://console.cloud.capawesome.io/organizations/_/git) page. A connection stores the provider and credentials and can be reused across all apps in your organization. If your organization already has a connection for your provider, you can skip this step.
1. Navigate to the **Git repository** page of your app in the Capawesome Cloud Console, select the Git connection, and choose the repository you want to connect. You can also connect a repository while creating an app or importing from Git.

Your Git repository is now connected to Capawesome Cloud and ready for building.

No Git? Or a Git server behind a firewall?

Connecting Git is optional. You can upload your local source files directly with the CLI's `--path` option instead — see [Build without Git Connection](https://capawesome.io/docs/cloud/native-builds/build-without-git/index.md). If your Git server sits behind a firewall, see [Access Git Behind a Firewall](https://capawesome.io/docs/cloud/native-builds/firewall-access/index.md) for your options.

## Step 3: Trigger First Build

Once your Git repository is connected, you can trigger your first build.

Use the [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) command:

```
npx @capawesome/cli apps:builds:create --platform android --git-ref main
```

1. Navigate to the [Builds](https://console.cloud.capawesome.io/apps/_/builds) page of your app.
1. Click **Build from Git**.
1. Select the **Git reference** (branch, tag, or commit) to build from.
1. Select the **Platform** (iOS or Android) and **Build type**. Choose **Debug** or **Simulator** for initial testing.
1. Click **Build** to start the build.

[Monitor the build](https://capawesome.io/docs/cloud/native-builds/monitor-builds/index.md) until it completes, then download the artifact.

For a quick first build, choose **Debug** on Android or **Simulator** on iOS — neither needs a [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/index.md). Note that an iOS Simulator build runs *only* in the iOS Simulator and cannot be installed on a physical iPhone (see Step 4).

Congratulations! You have created your first native build using Capawesome Cloud. 🎉

## Step 4: Install Your Build

How you run your build depends on the platform and build type you chose. For full instructions, see [Install a Build on a Device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md).

A **Debug** APK installs directly on a physical device — no signing required. Open the build's detail page, click **Install**, scan the QR code (or tap **Download** on the device), then open the APK to install. You'll need to [allow installs from unknown sources](https://capawesome.io/docs/cloud/native-builds/install-on-device/#android) first.

For a **Release** build, add a [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md).

A **Simulator** build runs only in the iOS Simulator on a Mac — it **cannot** be installed on a physical iPhone via QR code or download.

To install on a real device, create a **signed Development** build: register the device's UDID, add an [iOS signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/ios/index.md) and provisioning profile that includes the device, then install via the QR code. See [Install a Build on a Device](https://capawesome.io/docs/cloud/native-builds/install-on-device/#ios) for the full walkthrough.

## Bonus: Video Tutorials

Want to see the entire process in action? Check out these video tutorials:

This walkthrough covers the full Android build workflow — from triggering a build from your Git repository to downloading the artifact and testing it on your device.

This walkthrough covers how to create an iOS Simulator build as well as a signed Development build using an Apple developer certificate and provisioning profile.

## Next Steps

- **Sign Your Builds**

  ______________________________________________________________________

  Add a signing certificate to produce release builds ready for distribution.

  [Set up signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md)

- **Submit to the Stores**

  ______________________________________________________________________

  Send your builds straight to TestFlight and Google Play.

  [Set up App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/setup/index.md)

- **Automate Your Builds**

  ______________________________________________________________________

  Trigger builds automatically on every push or tag.

  [Set up Automations](https://capawesome.io/docs/cloud/automations/setup/index.md)

# Share a Build

Sometimes the people who need to test a build don't have a [Capawesome Cloud](/) account — a client, a beta tester, or a colleague on another team. Build sharing lets you hand them a single public link where they can view the build and install it on their device, no login required.

Sharing produces a public **share page** at `https://console.cloud.capawesome.io/app-build-shares/<id>`. Anyone with the link can open it — so share it only with people you trust. Build logs are never exposed, and you can [revoke a link](#revoke-a-share) at any time.

Only **succeeded** builds can be shared.

## Share a build

Use the [`apps:builds:share`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsshare) command to create a share for a build (or return the existing one):

```
npx @capawesome/cli apps:builds:share --app-id <app-id> --build-id <build-id>
```

Add an optional `--description` with instructions for testers (for example, what to test) and an optional `--expires-in-days` to have the link stop working after a number of days:

```
npx @capawesome/cli apps:builds:share \
  --app-id <app-id> \
  --build-id <build-id> \
  --description "Please test the new checkout flow" \
  --expires-in-days 7
```

Pass `--json` to get the share details as machine-readable output — including a `qrCodeUrl` you can embed anywhere:

```
{
  "id": "00000000-0000-0000-0000-000000000000",
  "qrCodeUrl": "https://...",
  "webUrl": "https://console.cloud.capawesome.io/app-build-shares/00000000-0000-0000-0000-000000000000",
  "expiresAt": "2026-01-01T00:00:00.000Z"
}
```

The `qrCodeUrl` points to a PNG image of a QR code for the share page, so you can drop it straight into a Slack message, a GitHub comment, or a pull request description.

To revoke a share, use the [`apps:builds:unshare`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsunshare) command — see [Revoke a share](#revoke-a-share).

Open the build's detail page and click **Share** to open the **Share build** dialog. Turn on the toggle to enable sharing, and optionally add a **Description** (shown to testers, e.g. what to test) and an **Expiration**. Click **Save**.

After saving, a dialog shows the **share link** so you can copy it right away. To copy the link again or to change the description or expiration later, reopen the dialog and save your changes — the link stays the same.

## The share page

The share page is public and requires no account. It shows:

- The build details: app, platform, type, build number, version, share date, and link expiration.
- The description you provided, if any.
- An **Installation** section with a QR code and a **Download** button for the build's artifact (APK for Android, IPA for iOS, ZIP for web builds).

For Android, the share page always offers the artifact of the [mobile form factor](https://capawesome.io/docs/cloud/native-builds/form-factors/index.md). A build without a mobile artifact shows no **Download** button.

Android testers scan the QR code with their device to download and install the APK directly. For iOS builds of type [ad-hoc, development, or enterprise](https://capawesome.io/docs/cloud/native-builds/build-types/index.md), the QR code installs the build over-the-air on the device — see [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) for the device requirements. All other builds offer the download only.

The QR code and download links are short-lived — a QR code is valid for 15 minutes, after which reloading the page generates a new one. **Build logs are never shown on the share page.**

## Share automatically after a build

You can share a build automatically as soon as it succeeds, without a separate command or click.

Add `--share` to [`apps:builds:create`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate) to share the build once it succeeds. Use `--share-description` and `--share-expires-in-days` to set the description and expiration:

```
npx @capawesome/cli apps:builds:create \
  --platform ios \
  --type ad-hoc \
  --git-ref main \
  --share \
  --share-description "Please test the new checkout flow" \
  --share-expires-in-days 7
```

With `--json`, the output includes an `appBuildShare` object with the share `id`, `qrCodeUrl`, `webUrl`, and `expiresAt`. `--share` waits for the build to finish, so it cannot be combined with `--detached`.

The official [`cloud-build-action`](https://github.com/capawesome-team/cloud-build-action) exposes sharing via the `share`, `shareDescription`, and `shareExpiresInDays` inputs, and returns the `shareWebUrl`, `shareQrCodeUrl`, and `shareExpiresAt` outputs. A common pattern is to post a pull request comment with the QR code and link after the build:

```
- uses: capawesome-team/cloud-build-action@v0.1.2
  id: build
  with:
    appId: "00000000-0000-0000-0000-000000000000"
    platform: ios
    type: ad-hoc
    gitRef: ${{ github.sha }}
    token: ${{ secrets.CAPAWESOME_TOKEN }}
    share: true
    shareDescription: "Please test this pull request"
    shareExpiresInDays: 7
- uses: actions/github-script@v7
  with:
    script: |
      const sha = context.payload.pull_request?.head?.sha || context.sha;
      const commitUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/commit/${sha}`;
      const expiresAt = '${{ steps.build.outputs.shareExpiresAt }}'.slice(0, 10);
      const body = [
        '### 📱 iOS build ready to test',
        '',
        '| Build | Commit | Expires |',
        '| --- | --- | --- |',
        `| [#${{ steps.build.outputs.buildNumber }}](${{ steps.build.outputs.buildUrl }}) | [\`${sha.slice(0, 7)}\`](${commitUrl}) | ${expiresAt} |`,
        '',
        `[<img src="${{ steps.build.outputs.shareQrCodeUrl }}" width="140" alt="QR code" />](${{ steps.build.outputs.shareWebUrl }})`,
        '',
        `**[Open share page →](${{ steps.build.outputs.shareWebUrl }})**`,
      ].join('\n');
      await github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body,
      });
```

See the [action README](https://github.com/capawesome-team/cloud-build-action) for the full example and [Native Builds with GitHub Actions](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md) for the workflow basics.

## Revoke a share

Use the [`apps:builds:unshare`](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsunshare) command to revoke the share link of a build:

```
npx @capawesome/cli apps:builds:unshare --app-id <app-id> --build-id <build-id>
```

Open the build's detail page, open the **Share build** dialog, turn the toggle off, and click **Save**.

The link is invalidated immediately and the share page stops working.

Re-enabling sharing creates a **new** link — the previous link stays permanently disabled, even if you turn sharing back on. There is no way to restore an old link, so anyone still holding it loses access for good.

## Privacy

Build sharing is designed to keep sensitive information out of reach:

- **Anyone with the link can access the share page.** Treat the link like a password and share it only with people you trust.
- **Build logs are never exposed** on the share page — only the metadata and installable artifacts.
- **Revoking a link takes effect immediately**, and re-enabling always mints a brand-new link that replaces the old one for good.

## Next steps

- [Install on a device](https://capawesome.io/docs/cloud/native-builds/install-on-device/index.md) — device requirements for installing shared iOS and Android builds.
- [Build types](https://capawesome.io/docs/cloud/native-builds/build-types/index.md) — which iOS types support the on-device **Install** button.
- [`apps:builds:share` reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildsshare) — every option for sharing from the CLI.

# Troubleshooting

## First, try Ask AI

On any failed build, click **Ask AI** in the Console to get a one-click diagnosis — the likely cause, an explanation, and a suggested fix — without leaving the dashboard. It's the fastest way to understand a failure, and it's included free in every plan with build minutes. See [Cloud Assist → Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md).

If you'd rather diagnose manually, match your error below.

## Error `invalid source release: 21`

The wrong Java version is being used. See [Override Java Version on Android Builds](https://capawesome.io/docs/cloud/native-builds/override-java-version/index.md) to set the `JAVA_VERSION` [environment variable](https://capawesome.io/docs/cloud/native-builds/environment-variables/#reserved-variables) to a supported major version such as `17` or `21`. For Capacitor 7, Java 21 is the default.

## Error `JavaScript heap out of memory`

Node.js ran out of memory during the web build. The default heap limit is ~2 GB, which may not be enough for large projects. Add `NODE_OPTIONS` as an [environment variable](https://capawesome.io/docs/cloud/native-builds/environments/index.md) with the value `--max-old-space-size=4096` (4 GB); use `8192` if that's still not enough.

Alternatively, set it directly in your build script:

```
"capawesome:build": "NODE_OPTIONS='--max-old-space-size=4096' npm run build"
```

## Build fails during signing

If an iOS or Android build fails while signing, confirm that the [signing certificate](https://capawesome.io/docs/cloud/native-builds/certificates/index.md) is configured correctly and that the provisioning profile matches the bundle ID and selected build type. For multi-target apps, see [Custom iOS provisioning profiles](https://capawesome.io/docs/cloud/native-builds/custom-ios-provisioning-profiles/index.md).

## Still stuck?

Reach out via [Support](https://capawesome.io/docs/support/index.md) with a link to the failed build and its logs.

# Configure Web Build Script

When building native apps with [Capawesome Cloud](/), the platform needs to generate your web assets before creating the native builds. This guide explains how Capawesome Cloud determines which npm script to use for building your web application.

## Build Script Priority

Capawesome Cloud follows a specific priority order when determining which script to execute for generating your web build:

1. **`capawesome:build` script**: If defined in your `package.json`, this script will be used.
1. **`build` script**: If `capawesome:build` is not defined, the standard `build` script will be used.
1. **Build failure**: If neither script exists, the web build will fail.

For most projects, the standard `build` script is sufficient:

```
{
  "scripts": {
    "build": "ionic build"
  }
}
```

If you need different build configurations for Capawesome Cloud builds versus local builds, define a `capawesome:build` script:

```
{
  "scripts": {
    "build": "ionic build",
    "capawesome:build": "ionic build --prod"
  }
}
```

This is useful when you need to apply production-specific optimizations, enable different build flags, or run additional build steps for native apps.

## Configuration File Override

You can also explicitly configure the web build command in your `capawesome.config.json` file:

```
{
  "cloud": {
    "apps": [
      {
        "appId": "your-app-id",
        "webBuildCommand": "npm run custom-build"
      }
    ]
  }
}
```

This approach gives you complete control over the build command and takes precedence over the automatic script detection. Learn more about configuration options in the [App Configuration](https://capawesome.io/docs/cloud/native-builds/configuration/index.md) documentation.

Build scripts can run authenticated Git commands against the linked repository, for example to fetch tags for versioning. See [Git access](https://capawesome.io/docs/cloud/native-builds/environment-variables/#git-access).

# Set Up Signing Certificates

When building apps, it is necessary to sign the resulting binaries to ensure their authenticity and integrity. Capawesome Cloud allows you to securely store and manage signing certificates for Android, iOS, and Web platforms.

- **Android**

  ______________________________________________________________________

  Configure keystores and signing keys for Android app builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/certificates/android/index.md)

- **iOS**

  ______________________________________________________________________

  Configure certificates and provisioning profiles for iOS app builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/certificates/ios/index.md)

- **Web**

  ______________________________________________________________________

  Configure PEM certificates for signing Live Update bundles.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/cloud/native-builds/certificates/web/index.md)

## Next steps

- [Security](https://capawesome.io/docs/cloud/security/index.md) — how to store, back up, and rotate the keys you upload.

# Android Signing Certificates

To build signed Android apps in Capawesome Cloud, you need to configure signing certificates. Android apps are signed using a Java Keystore (JKS) file containing your signing key. This certificate ensures the authenticity and integrity of your application. For a walkthrough that covers both Android and iOS end to end, see [How to Sign and Build Your Capacitor App in the Cloud](https://capawesome.io/blog/how-to-sign-and-build-your-capacitor-app-in-the-cloud/index.md).

AI-Assisted Setup

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill capawesome-cloud` and use the following prompt with your preferred AI coding assistant:

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up an Android signing certificate in Capawesome Cloud.
```

## Configuration

To create an Android signing certificate, navigate to the [Signing certificates](https://console.cloud.capawesome.io/apps/_/certificates) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for the certificate (e.g., "Production Android Key").
- **Platform**: Must be set to `Android`.
- **Keystore File**: The Java Keystore (JKS) file containing the signing key. Must have a `.jks` or `.keystore` extension.
- **Keystore password**: The password for the keystore file.
- **Key alias**: The alias of the key within the keystore.
- **Key password**: The password for the key alias.

Read on for detailed instructions on creating and obtaining these credentials.

## Obtaining Credentials

### Name

Choose a descriptive name that helps you identify the certificate's purpose (e.g., "Production Android Key", "Development Key", "Release Certificate"). This name is only used within Capawesome Cloud for organization purposes.

### Keystore File

A keystore file is required to sign your Android app. You can create a keystore using Android Studio or the `keytool` command-line utility.

Keep Your Keystore Secure

Store your keystore file and passwords securely. Losing access to your keystore or forgetting the passwords can prevent you from updating your app in the future, as you won't be able to sign new versions with the same key.

#### Create using Online Generator

The easiest way to create a keystore is using the [Capawesome Android Keystore Generator](/tools/android-keystore-generator/). Fill in the required fields and download the generated keystore file along with the credentials.

#### Create using Android Studio

1. Open Android Studio and create a new project or open an existing one.
1. Click on **Build** in the top menu, then select **Generate Signed Bundle / APK**.
1. Choose either **Android App Bundle** or **APK** and click **Next**.
1. Click on **Create new...** to generate a new keystore.
1. Fill in the required fields:
1. **Key store path**: Choose a location to save your keystore file (e.g., `my-release-key.jks`).
1. **Password**: Set a strong password for the keystore.
1. **Alias**: Choose an alias for your key (e.g., `my-key-alias`).
1. **Password**: Set a password for the key (can be the same as the keystore password).
1. **Validity (years)**: Set the validity period for the key (e.g., 25 years).
1. **Certificate**: Fill in your first and last name, organizational unit, organization, city or locality, state or province, and country code (XX).
1. Click **OK** to create the keystore.
1. Complete the signing process by following the prompts to generate the signed bundle or APK.

The keystore file will be saved to the location you specified.

#### Create using keytool

Alternatively, you can create a keystore using the `keytool` command-line utility that comes with the Java Development Kit (JDK):

```
keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias
```

You will be prompted to:

1. Enter a password for the keystore
1. Re-enter the password to confirm
1. Enter your name and organizational information
1. Enter a password for the key (press Enter to use the same password as the keystore)

The keystore file `my-release-key.jks` will be created in your current directory.

### Keystore Password

This is the password you set when creating the keystore. It protects access to the keystore file itself.

### Key Alias

The key alias is the name you assigned to the signing key within the keystore. If you created the keystore using Android Studio, this is the value you entered in the **Alias** field. If you used `keytool`, this is the value specified with the `-alias` parameter.

### Key Password

This is the password for the specific key identified by the key alias. It may be the same as the keystore password or different, depending on how you created the keystore.

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers setting up an Android signing certificate in Capawesome Cloud:

# iOS Signing Certificates

To build signed iOS apps in Capawesome Cloud, you need to configure signing certificates. iOS apps are signed using a certificate (`.p12` file) and one or more provisioning profiles (`.mobileprovision` files). These ensure the authenticity and integrity of your application and define which devices can run your app. If you're new to iOS code signing, read [iOS Certificates and Provisioning Profiles Explained](https://capawesome.io/blog/ios-certificates-and-provisioning-profiles-explained/index.md) for a beginner-friendly overview, or [How to Sign and Build Your Capacitor App in the Cloud](https://capawesome.io/blog/how-to-sign-and-build-your-capacitor-app-in-the-cloud/index.md) for a walkthrough that covers both Android and iOS end to end.

AI-Assisted Setup

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill capawesome-cloud` and use the following prompt with your preferred AI coding assistant:

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up an iOS signing certificate in Capawesome Cloud.
```

## Configuration

To create an iOS signing certificate, navigate to the [Signing certificates](https://console.cloud.capawesome.io/apps/_/certificates) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for the certificate (e.g., "Production iOS Certificate").
- **Platform**: Must be set to `iOS`.
- **Certificate File**: The `.p12` file containing the signing certificate and private key.
- **Certificate password**: The password for the `.p12` file.
- **Provisioning Profiles**: The `.mobileprovision` files associated with the app. In general, only one provisioning profile is needed. However, if you are using app extensions, you may need to upload multiple provisioning profiles (one for the main app and one for each extension).

Read on for detailed instructions on creating and obtaining these credentials.

## Obtaining Credentials

### Name

Choose a descriptive name that helps you identify the certificate's purpose (e.g., "Production iOS Certificate", "Development Certificate", "App Store Distribution"). This name is only used within Capawesome Cloud for organization purposes.

### Certificate File

A `.p12` file (Personal Information Exchange) containing your signing certificate and private key is required. You can export this file from Keychain Access or create a new certificate in the Apple Developer portal.

#### Create using Online Generator

The easiest way to create a certificate is using the [Capawesome iOS Certificate Generator](/tools/ios-certificate-generator/). The generator creates a signing certificate and private key, and exports them as a `.p12` file ready to upload to Capawesome Cloud. It also generates the Certificate Signing Request (CSR) file needed to create a certificate in the Apple Developer Portal.

#### Create using Keychain Access

If you need to create a new certificate:

1. Sign in to your [Apple Developer account](https://developer.apple.com/account).
1. Navigate to **Certificates, Identifiers & Profiles**.
1. Click on **Certificates** in the sidebar.
1. Click the **+** button to create a new certificate.
1. Select the appropriate certificate type:
   - For development: **Apple Development**
   - For production: **Apple Distribution**
1. Click **Continue**.
1. You'll be prompted to upload a Certificate Signing Request (CSR). To create a CSR:
   1. Open **Keychain Access** on your Mac.
   1. From the menu bar, select **Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority**.
   1. Enter your email address and name.
   1. Select **Saved to disk** and click **Continue**.
   1. Save the CSR file to your computer.
1. Upload the CSR file in the Apple Developer portal and click **Continue**.
1. Download the generated certificate file (`.cer`).
1. Double-click the downloaded `.cer` file to install it in Keychain Access.
1. Follow the **Export from Keychain Access** instructions above to export the certificate as a `.p12` file.

#### Export from Keychain Access

If you already have a signing certificate installed on your Mac:

1. Open **Keychain Access** (Applications > Utilities > Keychain Access).
1. In the left sidebar, select **login** and then **My Certificates**.
1. Look for certificates named:
   - **Apple Distribution: [Your Name]** (for App Store/Production builds)
   - **Apple Development: [Your Name]** (for development builds)
1. Expand the certificate to see the private key underneath (indicated by a key icon).
1. Select **both** the certificate **and** its private key by holding Command and clicking both items.
1. Right-click on the selection and choose **Export 2 items...**.
1. Choose a name for the file (e.g., `certificate.p12`) and select **Personal Information Exchange (.p12)** as the file format.
1. Click **Save**.
1. Set a password when prompted. This password will be required when uploading the certificate to Capawesome Cloud.
1. You may be prompted to enter your macOS user password to allow the export.

Private key required

You must export both the certificate and its private key together. If you don't see a private key under your certificate in Keychain Access, the certificate may have been installed without the private key, and you'll need to create a new certificate or obtain it from the original creator.

### Certificate Password

This is the password you set when exporting the `.p12` file from Keychain Access. You'll need to provide this password when uploading the certificate to Capawesome Cloud.

### Provisioning Profiles

Provisioning profiles are required to run your app on devices and define which devices and capabilities your app can use. You need to provide one or more `.mobileprovision` files.

#### Find Locally

If you've previously built your app in Xcode, provisioning profiles may already be available on your Mac:

1. Open **Terminal**.

1. Run the following command to list all installed provisioning profiles and their details:

   ```
   for f in ~/Library/MobileDevice/Provisioning\ Profiles/*.mobileprovision; do echo "=== $f ==="; security cms -D -i "$f" 2>/dev/null | grep -A 1 'application-identifier\|<key>Name</key>\|ExpirationDate' | grep -v '^--$'; echo; done
   ```

1. Identify the relevant provisioning profile(s) by looking for the **Name** and **application-identifier** fields.

1. Copy the desired `.mobileprovision` file(s) from `~/Library/MobileDevice/Provisioning Profiles/` to a location where you can easily access them for upload:

   ```
   cp ~/Library/MobileDevice/Provisioning\ Profiles/<profile-uuid>.mobileprovision ~/Desktop/
   ```

#### Create and Download from Apple Developer Portal

To create a new provisioning profile or download an existing one:

1. Sign in to your [Apple Developer account](https://developer.apple.com/account).
1. Navigate to **Certificates, Identifiers & Profiles**.
1. Click on **Profiles** in the sidebar.
1. To create a new profile, click the **+** button:
   1. Select the appropriate profile type:
      - For development: **iOS App Development**
      - For production: **App Store** (for App Store and TestFlight) or **Ad Hoc** (for enterprise distribution)
   1. Click **Continue**.
   1. Select your **App ID** from the dropdown menu and click **Continue**.
   1. Select the certificate(s) to include in this profile and click **Continue**.
   1. For development profiles, select the devices to include and click **Continue**.
   1. Enter a **Provisioning Profile Name** and click **Generate**.
1. Download the generated provisioning profile (`.mobileprovision` file).
1. Repeat this process for any app extensions if your app includes them. Each extension requires its own provisioning profile matching its bundle identifier.

Multiple provisioning profiles

Apps with extensions (e.g., widgets, share extensions) require a separate provisioning profile for each target. Capawesome Cloud automatically matches profiles to targets based on bundle identifiers. For non-standard bundle ID patterns, see the [Custom iOS Provisioning Profiles](https://capawesome.io/docs/cloud/native-builds/custom-ios-provisioning-profiles/index.md) guide.

Profile expiration

Provisioning profiles expire after a certain period (typically one year). If your builds fail due to expired profiles, you'll need to regenerate and upload new ones in the Apple Developer portal.

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers setting up an iOS signing certificate in Capawesome Cloud:

# Web Signing Certificates

To sign Live Update bundles in Capawesome Cloud, you need to configure a signing certificate. Web apps use a PEM certificate file containing a private key to sign bundles, ensuring the authenticity and integrity of your Live Updates.

AI-Assisted Setup

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill capawesome-cloud` and use the following prompt with your preferred AI coding assistant:

```
Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up a Web signing certificate in Capawesome Cloud.
```

## Configuration

To create a web signing certificate, navigate to the [Signing certificates](https://console.cloud.capawesome.io/apps/_/certificates) page in the Capawesome Cloud Console and provide the following information:

- **Name**: A descriptive name for the certificate (e.g., "Production Web Certificate").
- **Platform**: Must be set to `Web`.
- **Certificate File**: The PEM file containing the private key. Must have a `.pem` extension.

Read on for detailed instructions on creating and obtaining these credentials.

## Obtaining Credentials

### Name

Choose a descriptive name that helps you identify the certificate's purpose (e.g., "Production Web Certificate", "Development Certificate"). This name is only used within Capawesome Cloud for organization purposes.

### Certificate File

A PEM file containing your private key is required to sign Live Update bundles. You can generate a key pair using the Capawesome CLI:

```
npx @capawesome/cli apps:liveupdates:generatesigningkey
```

This creates a `private.pem` and `public.pem` file in the current directory. Upload the `private.pem` file as the certificate file in the Capawesome Cloud Console.

You can also customize the output paths and key size:

```
npx @capawesome/cli apps:liveupdates:generatesigningkey --private-key /path/to/private.pem --public-key /path/to/public.pem --key-size 4096
```

Keep your private key secure

Store your private key in a secure location, add it to your `.gitignore`, and never commit it to version control. If you lose your private key, you will need to generate a new key pair and reconfigure your app.

For more information on code signing, see the [Code Signing](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) guide.

# Integrations

Connect native builds to the rest of your toolchain — trigger builds from your CI/CD pipeline, or upload source maps to your error monitoring service during the build.

## CI/CD pipelines

Trigger native builds from your CI/CD pipeline. The setup is the same across providers — only the pipeline syntax differs.

- **Azure DevOps**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/native-builds/integrations/azure-devops/index.md)

- **Bitbucket Pipelines**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/native-builds/integrations/bitbucket-pipelines/index.md)

- **GitHub Actions**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md)

- **GitLab CI/CD**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/native-builds/integrations/gitlab-ci/index.md)

Official GitHub Action

On GitHub? The official [`cloud-build-action`](https://github.com/capawesome-team/cloud-build-action) triggers a native build in a single step — see [GitHub Actions](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md).

The build itself always runs on Capawesome Cloud's hosted macOS runners, so your CI job doesn't need a Mac, Xcode, or any native toolchain — it only authenticates and starts the build. Every pipeline follows the same shape:

1. **Authenticate** — create an API token, store it as a CI secret, and log in with `--token`.
1. **Trigger the build** — `apps:builds:create --platform ios` (or `android`), with `--git-ref` pointing at the commit to build and `--yes` to skip confirmation prompts.
1. **Submit (optional)** — pass `--destination` to send the finished build to TestFlight or Google Play, turning the pipeline into a full release.

Pin the CLI version (`@capawesome/cli@<version>`) so pipelines are reproducible, and prefer manual dispatch over auto-on-merge so builds run when you decide.

For signing certificates, environments, and store submissions in CI, see [Certificates](https://capawesome.io/docs/cloud/native-builds/certificates/index.md), [Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md), and [App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md). For ready-to-run pipelines, see [Sample Projects](https://capawesome.io/docs/cloud/native-builds/sample-projects/index.md).

## Error monitoring

Upload source maps to your error monitoring service during the build to get readable stack traces.

- **Sentry**

  ______________________________________________________________________

  [Set up](https://capawesome.io/docs/cloud/native-builds/integrations/sentry/index.md)

# Azure DevOps

Trigger native builds from Azure Pipelines. The build runs in Capawesome Cloud, so the pipeline only authenticates and starts the build.

## Prerequisites

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in Capawesome Cloud and store it as a secret pipeline variable named `CAPAWESOME_TOKEN`.

## Pipeline

azure-pipelines.yml

```
trigger: none

pool:
  vmImage: ubuntu-latest

variables:
  CAPAWESOME_CLI_VERSION: "4.9.3"
  CAPAWESOME_CLOUD_APP_ID: "00000000-0000-0000-0000-000000000000"

steps:
  - script: npx @capawesome/cli@$(CAPAWESOME_CLI_VERSION) login --token $(CAPAWESOME_TOKEN)
    displayName: Authenticate with Capawesome Cloud
  - script: >
      npx @capawesome/cli@$(CAPAWESOME_CLI_VERSION) apps:builds:create
      --app-id $(CAPAWESOME_CLOUD_APP_ID)
      --platform ios
      --git-ref $(Build.SourceVersion)
      --yes
    displayName: Create build
```

Pin the CLI version for reproducible runs. To attach a signing certificate or environment, pass the relevant flags — see the [CLI reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate).

# Bitbucket Pipelines

Trigger native builds from Bitbucket Pipelines. The build runs in Capawesome Cloud, so the pipeline only authenticates and starts the build.

## Prerequisites

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in Capawesome Cloud and store it as a secured repository variable named `CAPAWESOME_TOKEN`.

## Pipeline

bitbucket-pipelines.yml

```
image: node:24

pipelines:
  custom:
    native-build:
      - step:
          name: Create native build
          script:
            - CLI=4.9.3
            - APP_ID=00000000-0000-0000-0000-000000000000
            - npx @capawesome/cli@$CLI login --token $CAPAWESOME_TOKEN
            - npx @capawesome/cli@$CLI apps:builds:create --app-id $APP_ID --platform android --git-ref $BITBUCKET_COMMIT --yes
```

Pin the CLI version for reproducible runs. To attach a signing certificate or environment, pass the relevant flags — see the [CLI reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate).

# GitHub Actions

Trigger native builds from [GitHub Actions](https://github.com/features/actions). The build itself runs in Capawesome Cloud, so the workflow only needs to start it — using the official **Capawesome Cloud Build Action** (recommended) or the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md).

## Prerequisites

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in Capawesome Cloud and store it as a repository secret named `CAPAWESOME_TOKEN`.

## Workflow

The official [`cloud-build-action`](https://github.com/capawesome-team/cloud-build-action) starts the build in a single step and exposes the build number and URL as outputs:

.github/workflows/native-build.yml

```
name: Native Build
on:
  workflow_dispatch:
    inputs:
      platform:
        description: "Platform (ios or android)"
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: capawesome-team/cloud-build-action@v0.1.0
        with:
          appId: "00000000-0000-0000-0000-000000000000"
          platform: ${{ inputs.platform }}
          gitRef: ${{ github.sha }}
          token: ${{ secrets.CAPAWESOME_TOKEN }}
```

The action exposes all the build options as inputs — including `type`, `certificate`, `environment`, `channel`/`destination`, and artifact downloads (`apk`/`aab`/`ipa`/`zip`). See the [action README](https://github.com/capawesome-team/cloud-build-action) for the full list.

To share the build with testers after it succeeds, set the `share` input (with optional `shareDescription` and `shareExpiresInDays`) and read the `shareUrl`, `shareQrCodeUrl`, and `shareExpiresAt` outputs — for example to post a pull request comment with the QR code and link. See [Share a build](https://capawesome.io/docs/cloud/native-builds/share-a-build/#share-automatically-after-a-build).

Prefer full control, or running on a non-GitHub CI? Use the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) directly:

.github/workflows/native-build.yml

```
name: Native Build
on:
  workflow_dispatch:
    inputs:
      platform:
        description: "Platform (android, ios, or web)"
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npx @capawesome/cli login --token ${{ secrets.CAPAWESOME_TOKEN }}
      - run: |
          npx @capawesome/cli apps:builds:create \
            --app-id 00000000-0000-0000-0000-000000000000 \
            --platform ${{ inputs.platform }} \
            --git-ref ${{ github.sha }} \
            --yes
```

Pin the action (or the CLI version) to a specific release for reproducible runs, and prefer `workflow_dispatch` so builds run when you choose. To attach a signing certificate or environment, pass the relevant inputs — see the [action README](https://github.com/capawesome-team/cloud-build-action) or the [CLI reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate).

# GitLab CI/CD

Trigger native builds from GitLab CI/CD. The build runs in Capawesome Cloud, so the pipeline only authenticates and starts the build.

## Prerequisites

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in Capawesome Cloud and store it as a CI/CD variable named `CAPAWESOME_TOKEN` (masked).

## Pipeline

.gitlab-ci.yml

```
variables:
  CAPAWESOME_CLI_VERSION: "4.9.3"
  CAPAWESOME_CLOUD_APP_ID: "00000000-0000-0000-0000-000000000000"

native-build:
  image: node:24
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
  script:
    - npx @capawesome/cli@$CAPAWESOME_CLI_VERSION login --token $CAPAWESOME_TOKEN
    - >
      npx @capawesome/cli@$CAPAWESOME_CLI_VERSION apps:builds:create
      --app-id $CAPAWESOME_CLOUD_APP_ID
      --platform android
      --git-ref $CI_COMMIT_SHA
      --yes
```

Pin the CLI version for reproducible runs. To attach a signing certificate or environment, pass the relevant flags — see the [CLI reference](https://capawesome.io/docs/cloud/cli/commands/#appsbuildscreate).

# Sentry

If you monitor your app with [Sentry](https://sentry.io/), uploading source maps during the build turns minified JavaScript stack traces into readable ones. This guide shows how to upload source maps automatically during Capawesome Cloud native builds — with your Sentry auth token stored safely as a secret.

## Prerequisites

- Your app is set up with the [Sentry Capacitor SDK](https://docs.sentry.io/platforms/javascript/guides/capacitor/).
- You have a Sentry auth token. An [organization auth token](https://docs.sentry.io/account/auth-tokens/) is recommended — it is pre-scoped for CI tasks like source map uploads.

## Store your Sentry credentials

Add your Sentry credentials to a [custom environment](https://capawesome.io/docs/cloud/native-builds/environments/index.md) so they are available during the build. Store the auth token as a **secret** — it is encrypted and never appears in build logs — and the organization and project slugs as regular variables:

```
npx @capawesome/cli apps:environments:set \
  --variable SENTRY_ORG=your-org-slug \
  --variable SENTRY_PROJECT=your-project-slug \
  --secret SENTRY_AUTH_TOKEN=sntrys_your_token
```

On the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page, choose **Manage environment variables** from the environment's actions menu and add `SENTRY_ORG` and `SENTRY_PROJECT`. Then choose **Manage environment secrets** and add `SENTRY_AUTH_TOKEN`.

`SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` are the standard environment variables that both the Sentry CLI and Sentry's bundler plugins pick up automatically.

Select the environment when you [trigger a build](https://capawesome.io/docs/cloud/native-builds/builds/index.md), or [set it as the default environment](https://capawesome.io/docs/cloud/native-builds/environments/#set-a-default-environment) so it applies to every build.

## Upload source maps during the build

There are two ways to upload source maps during a build. The bundler plugin is recommended — it hooks into your existing web build, so no build script changes are needed.

### Option 1: Sentry bundler plugin (recommended)

Sentry provides plugins for all common bundlers: [`@sentry/vite-plugin`](https://www.npmjs.com/package/@sentry/vite-plugin), [`@sentry/webpack-plugin`](https://www.npmjs.com/package/@sentry/webpack-plugin), [`@sentry/esbuild-plugin`](https://www.npmjs.com/package/@sentry/esbuild-plugin), and [`@sentry/rollup-plugin`](https://www.npmjs.com/package/@sentry/rollup-plugin). The plugin generates and uploads source maps automatically whenever your web build runs. For Vite:

vite.config.js

```
import { defineConfig } from 'vite';
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: {
    sourcemap: 'hidden',
  },
  plugins: [
    // The Sentry plugin must be the last plugin.
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: {
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
});
```

That's it — no changes to your build script are required. During a Capawesome Cloud build, the plugin finds the credentials from your environment and uploads the source maps. In local builds without `SENTRY_AUTH_TOKEN`, the plugin simply skips the upload instead of failing, so your development workflow is unaffected.

The `filesToDeleteAfterUpload` option removes the `.map` files once they are uploaded, so they are not copied into the native app — shipped source maps would increase your app size and expose your source code. Symbolication is unaffected, since Sentry uses the uploaded copies.

### Option 2: Sentry CLI

Alternatively, run the [Sentry CLI](https://docs.sentry.io/platforms/javascript/guides/capacitor/sourcemaps/uploading/) after your web build. Since Capawesome Cloud runs the `capawesome:build` script from your `package.json` when present (see [Configure Web Build Script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md)), chain the upload there:

package.json

```
{
  "scripts": {
    "build": "vite build",
    "capawesome:build": "npm run build && npx @sentry/cli sourcemaps inject dist && npx @sentry/cli sourcemaps upload dist && find dist -name '*.map' -delete"
  }
}
```

Replace `dist` with your web output directory (e.g. `www` or `build`). The `inject` command stamps debug IDs into the built files before they are copied into the native app, so Sentry can match stack traces to the uploaded source maps without any release configuration. The final `find` command removes the `.map` files after the upload so they are not shipped inside your app. Your local `npm run build` stays untouched.

Tag releases with build information

You can use the [default variables](https://capawesome.io/docs/cloud/native-builds/environment-variables/index.md) to associate the upload with a release, for example `--release $CI_BUILD_ID`. The release name must match the `release` option in your `Sentry.init` configuration. With debug IDs, this is optional — source maps resolve without it.

## Verify the upload

After triggering a build, check the [build logs](https://capawesome.io/docs/cloud/native-builds/build-logs/index.md) for the Sentry upload output. In Sentry, the uploaded artifacts appear under your project's **Source Maps** settings — and new errors from the web layer of your app now show readable stack traces.

## Native crash symbolication

Source maps cover the web layer of your app. To also get readable native crash reports, configure Sentry's native tooling in your project — since Capawesome Cloud runs your standard Gradle and Xcode builds, it runs during cloud builds too, using the same `SENTRY_AUTH_TOKEN` secret:

- **Android**: The [Sentry Android Gradle plugin](https://docs.sentry.io/platforms/android/configuration/gradle/) uploads ProGuard/R8 mapping files during the Gradle build.
- **iOS**: Upload dSYM files with an [Xcode build phase](https://docs.sentry.io/platforms/apple/guides/ios/dsym/).

## Next steps

- [Set Up Environments](https://capawesome.io/docs/cloud/native-builds/environments/index.md) — manage variables and secrets for your builds.
- [Configure Web Build Script](https://capawesome.io/docs/cloud/native-builds/web-build-script/index.md) — control which script builds your web assets.
- [Build Logs](https://capawesome.io/docs/cloud/native-builds/build-logs/index.md) — inspect the output of your builds.

# Organizations

An **organization** owns your apps, members, and billing in Capawesome Cloud. Every app belongs to exactly one organization, and you can belong to multiple organizations.

## Create an organization

A first organization is created for you when you sign up. To create another, open the [Console](https://console.cloud.capawesome.io) and create a new organization from the organization switcher.

## Manage your organization

- **[Members](https://capawesome.io/docs/cloud/organizations/memberships/index.md)** — invite and manage people in the organization.
- **[Roles & permissions](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md)** — control what each member can do.
- **[Teams](https://capawesome.io/docs/cloud/organizations/teams/index.md)** — group members and assign per-app access.
- **[Single sign-on (SSO)](https://capawesome.io/docs/cloud/organizations/sso/index.md)** — enforce SSO for your members.
- **[Two-factor enforcement](https://capawesome.io/docs/cloud/organizations/two-factor-authentication/index.md)** — require 2FA for members.
- **[Network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md)** — limit access by IP address or country.
- **[Audit logs](https://capawesome.io/docs/cloud/organizations/audit-logs/index.md)** — review actions across the organization.
- **[Billing](https://capawesome.io/docs/cloud/organizations/billing/index.md)** — manage your plan, invoices, and payment.

## Ownership

Each organization has an owner with full control, including billing and the ability to delete the organization. Ownership can be transferred to another member, and an organization can be deleted from its settings in the Console.

# Audit Logs

Audit logs provide a detailed record of actions taken within Capawesome Cloud. They are essential for tracking changes, monitoring user activity, and ensuring compliance with organizational policies. Audit logs can be accessed through the Capawesome Cloud Console.

## Accessing Audit Logs

To access audit logs, you can use the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/audit-logs). Simply navigate to the "Audit logs" section under your organization. Here, you can filter logs by entity type, entity ID, action type and user.

Only organization owners and admins can access audit logs.

## Entities

The following entities are tracked in the audit logs:

- **Apps**: Actions related to app creation, updates, and deletions.
- **Bundles**: Actions related to bundle creation, updates, and deletions.
- **Channels**: Actions related to channel creation, updates, and deletions.
- **Invitations**: Actions related to invitations sent, accepted, or revoked.
- **Members**: Actions related to member role changes and removals.
- **Organizations**: Actions related to organization settings and member management.
- **Subscriptions**: Actions related to subscription changes and billing updates.

We are continuously working to enhance our audit logging capabilities. If you have any suggestions or need additional features, please feel free to reach out to our support team.

# Members

Members are the people in your Capawesome Cloud organization. You can invite users, assign them a [role](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md), and manage their access.

## Roles

When you invite a member, you assign a **role** that controls what they can do in the organization. See [Roles & permissions](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) for the full list of roles and the permissions matrix.

## Inviting users

To invite a user to your organization:

1. Go to the **Invitations** page in the [Console](https://console.cloud.capawesome.io/organizations/_/invitations).
1. Click **Create invitation**.
1. Enter the user's email address.
1. Select the [role](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) to assign.
1. Click **Create** to send the invitation.

Once the user accepts, they become a member with the assigned role.

## Managing members

To manage members:

1. Go to the **Members** page in the [Console](https://console.cloud.capawesome.io/organizations/_/members).
1. Review the list of members, their roles, and their status.
1. Change a member's role with the **Edit** action.
1. Remove a member with the **Delete** action.

# Network Restrictions

Network restrictions limit which networks may reach your [organization](https://capawesome.io/docs/cloud/organizations/index.md). You can allow access from specific IP addresses and CIDR ranges, from specific countries, or both. Both restrictions are disabled by default.

## How Network Restrictions Work

The two restrictions are independent, and you can enable either one or both:

- **IP allowlist** — exact IPv4 and IPv6 addresses and CIDR ranges.
- **Country allowlist** — ISO 3166-1 alpha-2 country codes, such as `DE` or `US`.

If you enable both, a request must satisfy both to be allowed. An empty allowlist means that restriction is switched off.

Both restrictions fail closed. If a restriction is enabled and the IP address or country of a request cannot be determined, the request is denied. Requests coming from the Tor network never match a country allowlist.

Warning

An IP allowlist and a country allowlist are not equally strong. An IP allowlist is a real perimeter. A country allowlist is a coarse filter that anyone can work around by renting a server in an allowed country. Don't rely on a country allowlist alone where you need a security boundary.

## What Is Restricted

Network restrictions apply to requests made with a session (the Console) and with an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) (the CLI and the Cloud API). They also apply to SSO sign-in, and to accepting an invitation to the organization.

Members who are not part of the organization see the usual authorization error and are never told that the organization restricts access by network.

## Restricting Access by IP Address

1. Go to the **Settings** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/settings).
1. Scroll to the **Security** section.
1. Enable **Restrict access by IP address**.
1. Enter each IP address or CIDR range and press **Enter** after each one.
1. Click on the **Save** button.

Both address families are supported, as single addresses or as CIDR ranges — for example `203.0.113.4`, `203.0.113.0/24`, `2001:db8::1`, or `2001:db8::/32`. You can add up to 250 entries.

To turn the restriction off again, disable **Restrict access by IP address** and save.

## Restricting Access by Country

1. Go to the **Settings** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/settings).
1. Scroll to the **Security** section.
1. Enable **Restrict access by country**.
1. Select each country you want to allow.
1. Click on the **Save** button.

You can add up to 250 countries. The country of a request is determined from its IP address, so a member connecting through a VPN or proxy in another country is treated as being in that country.

To turn the restriction off again, disable **Restrict access by country** and save.

## Avoiding Lockout

Because you are subject to your own allowlist, an allowlist that excludes you is rejected when you save it. Make sure your own IP address and country are covered before saving.

You can look them up on the [Sessions](https://console.cloud.capawesome.io/settings/sessions) page, which shows the IP address and country of your current session. The Console links to it from both fields.

Keep in mind that this protects only you. Other members, and any automation using an API token, can still be locked out by an allowlist that doesn't cover them. Before you save, consider:

- **Members working remotely or from other offices.** Home connections usually have dynamic IP addresses that change without notice.
- **CI/CD pipelines.** A pipeline running on GitHub Actions, GitLab CI, or a similar hosted runner authenticates with an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) and is subject to the IP allowlist. Either allowlist your provider's egress ranges, or use Capawesome-hosted builds, which are not restricted.
- **Members travelling abroad**, if you use a country allowlist.

## Regaining Access

If everyone with permission to change the settings ends up outside the allowlist, the restriction can no longer be lifted from the Console — the check runs before the request reaches the settings. In that case, [contact Capawesome support](https://capawesome.io/docs/support/index.md) to have the restriction removed.

## Next Steps

- [Roles & permissions](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) — control what each member can do.
- [Two-factor enforcement](https://capawesome.io/docs/cloud/organizations/two-factor-authentication/index.md) — require 2FA for members.
- [Single sign-on (SSO)](https://capawesome.io/docs/cloud/organizations/sso/index.md) — enforce SSO for your members.
- [Audit logs](https://capawesome.io/docs/cloud/organizations/audit-logs/index.md) — review actions across the organization.

# Roles & Permissions

Capawesome Cloud provides several predefined roles you can assign to [members](https://capawesome.io/docs/cloud/organizations/memberships/index.md):

- **Owner** — full access to all resources and settings.
- **Admin** — can manage users and settings, but cannot delete the organization.
- **Billing** — can manage billing and subscription settings.
- **Member** — can access shared app resources, with limited organization permissions.
- **Viewer** — can view apps and app resources.

## Permissions matrix

| Action                                      | Owner | Admin | Billing | Member | Viewer |
| ------------------------------------------- | ----- | ----- | ------- | ------ | ------ |
| See and edit billing and subscription       | ✓     |       | ✓       |        |        |
| Manage organization ownership               | ✓     |       |         |        |        |
| Manage organization settings                | ✓     | ✓     |         |        |        |
| Create and manage apps                      | ✓     | ✓     |         |        |        |
| Create and manage invitations               | ✓     | ✓     |         |        |        |
| Create and manage members                   | ✓     | ✓     |         |        |        |
| Create and manage teams                     | ✓     | ✓     |         |        |        |
| View apps and app resources                 | ✓     | ✓     |         | ✓      | ✓      |
| Create and manage app builds                | ✓     | ✓     |         | ✓      |        |
| Create and manage app certificates          | ✓     | ✓     |         | ✓      |        |
| Create and manage app channels              | ✓     | ✓     |         | ✓      |        |
| Create and manage app deployments           | ✓     | ✓     |         | ✓      |        |
| Create and manage app destinations          | ✓     | ✓     |         | ✓      |        |
| Create and manage app devices               | ✓     | ✓     |         | ✓      |        |
| Create and manage app environments          | ✓     | ✓     |         | ✓      |        |
| Create and manage app webhooks              | ✓     | ✓     |         | ✓      |        |
| Use Ask AI on failed builds and deployments | ✓     | ✓     |         | ✓      |        |
| Create and manage license keys              | ✓     | ✓     |         |        |        |
| View and copy license keys                  | ✓     | ✓     |         | ✓      |        |
| Subscribe to usage-limit notifications      | ✓     | ✓     |         |        |        |
| Delete an organization                      | ✓     |       |         |        |        |

Assign a role when you [invite a member](https://capawesome.io/docs/cloud/organizations/memberships/index.md), and change it later from the Members page.

# Teams

Teams allow you to organize members within your organization and control access to specific apps. By creating teams, you can ensure that members only have access to the apps they need to work with.

## How Teams Work

Teams are groups of members within an organization that can be assigned access to specific apps. Each team can have multiple members, and each member can belong to multiple teams. Apps can be assigned to multiple teams as well.

Relationship between Members, Teams, and Apps in Capawesome Cloud

When a member is part of a team, they gain access to all apps assigned to that team. If a member is not part of any team, they will not have access to any apps in the organization (except for Owners and Admins).

## Creating Teams

To create a team in your organization:

1. Go to the **Teams** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/teams).
1. Click on the **Create team** button.
1. Enter a name and optional description for the team.
1. Click **Create** to create the team.
1. After creation, you can add apps and members to the team by clicking on "Manage apps" and "Manage members" in the "Actions" menu of the team.

Team Assignments Required

As soon as the first team is created in an organization, all existing members (except Owners and Admins) will lose access to all apps until they are assigned to a team. Make sure to assign members to teams after creating the first team to restore their access.

## Managing Apps

To manage apps within a team:

1. Go to the **Teams** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/teams).
1. Click on "Manage apps" in the "Actions" menu of the desired team.
1. Click on **Add apps** to assign apps to the team.
1. Select the apps you want to add and click **Add**.

## Managing Members

To manage members within a team:

1. Go to the **Teams** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/teams).
1. Click on "Manage members" in the "Actions" menu of the desired team.
1. Click on **Add members** to assign members to the team.
1. Select the members you want to add and click **Add**.

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers creating and managing teams in Capawesome Cloud:

# Two-Factor Authentication

For enhanced security, Capawesome Cloud allows organizations to enforce two-factor authentication (2FA) for all members. When 2FA enforcement is enabled, all members of the organization must have 2FA enabled on their accounts to remain part of the organization.

## How 2FA Enforcement Works

When 2FA enforcement is enabled for an organization, the following rules apply:

- **Existing members retain access**: Members who are already part of the organization when 2FA enforcement is enabled will remain in the organization, even if they haven't enabled 2FA yet. They can continue to access the organization until they enable 2FA themselves or are manually removed and re-invited to enforce the requirement.
- **New members must have 2FA enabled**: New members or members accepting invitations must have 2FA enabled on their account before they can join the organization.
- **Members cannot disable 2FA**: Once a member has enabled 2FA and joined an organization with 2FA enforcement enabled, they cannot disable 2FA on their account while they remain a member of the organization.

## Enabling 2FA Enforcement

To enable 2FA enforcement for your organization:

1. Go to the **Settings** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/settings).
1. Scroll to the **Security** section.
1. Enable **Require two-factor authentication**.
1. Click on the **Save** button.

Once enabled, existing members will retain access to the organization regardless of their 2FA status. However, new members will be required to have 2FA enabled before they can join. To enforce 2FA for existing members without 2FA, you will need to manually remove them from the organization and re-invite them.

Only organization owners and admins can change this setting.

## Disabling 2FA Enforcement

To disable 2FA enforcement for your organization:

1. Go to the **Settings** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/settings).
1. Scroll to the **Security** section.
1. Disable **Require two-factor authentication**.
1. Click on the **Save** button.

Once disabled, members will no longer be required to have 2FA enabled, and they can disable 2FA on their accounts if they choose to do so.

## Setting Up 2FA

For information on how to set up two-factor authentication on your account, please refer to the [Authentication](https://capawesome.io/docs/cloud/accounts/authentication/#two-factor-authentication-mfa) guide.

## Next Steps

- [Network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md) — limit access by IP address or country.
- [Single sign-on (SSO)](https://capawesome.io/docs/cloud/organizations/sso/index.md) — enforce SSO for your members.
- [Roles & permissions](https://capawesome.io/docs/cloud/organizations/roles-and-permissions/index.md) — control what each member can do.

# Billing

The Billing section covers everything related to subscriptions, payment methods, and invoices for your Capawesome Cloud organization. All payments and invoicing are handled by our Merchant of Record (MoR) partners, [Polar](https://polar.sh/) and [Lemon Squeezy](https://www.lemonsqueezy.com/), which take care of payment processing, tax compliance, and invoicing on our behalf.

## Accessing the Billing Page

To manage billing for your organization, go to the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing).

Only members with the **Owner** or **Billing** role can access the Billing page. See [Organization and User Management](https://capawesome.io/docs/cloud/organizations/memberships/index.md) for details on assigning roles.

## What You Can Do

From the Billing page, you can:

- [Manage Plans & Billing](https://capawesome.io/docs/cloud/organizations/billing/manage/index.md) — subscribe to a plan, upgrade or downgrade, switch billing interval, cancel, and update payment or billing details.
- [Invoices](https://capawesome.io/docs/cloud/organizations/billing/invoices/index.md) — view payment history and download invoices and receipts.
- [FAQ](https://capawesome.io/docs/cloud/organizations/billing/faq/index.md) — answers to common billing questions.

## Merchant of Record

Capawesome uses a Merchant of Record (MoR) model for all paid subscriptions. This means Polar or Lemon Squeezy is the seller of record for your subscription and is responsible for collecting payments, charging applicable taxes (such as VAT or sales tax), and issuing invoices.

- All new customers are onboarded through [Polar](https://polar.sh/).
- [Lemon Squeezy](https://www.lemonsqueezy.com/) is available as an alternative if you run into payment issues with Polar.

If you need to switch your organization from one provider to the other, please [contact support](https://capawesome.io/docs/support/index.md).

# Billing FAQ

Answers to the most common questions about billing for your Capawesome Cloud organization. For detailed walkthroughs, see [Manage Plans & Billing](https://capawesome.io/docs/cloud/organizations/billing/manage/index.md) and [Invoices](https://capawesome.io/docs/cloud/organizations/billing/invoices/index.md).

## Is there a free trial?

Yes. New organizations can start a **14-day free trial** on any paid plan. A valid payment method is required upfront to prevent misuse of our Cloud infrastructure, but no charges are made during the trial. See [Free Trial](https://capawesome.io/docs/cloud/organizations/billing/manage/#free-trial) for details.

## How do I cancel my subscription?

Open the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing) and click **Cancel Subscription**. Cancellation takes effect at the end of the current billing period. See [Canceling Your Subscription](https://capawesome.io/docs/cloud/organizations/billing/manage/#canceling-your-subscription).

## How do I upgrade or downgrade my plan?

Upgrades take effect immediately and are invoiced right away. Downgrades take effect at the next renewal, with any price difference automatically applied as credit to upcoming invoices. See [Upgrading Your Plan](https://capawesome.io/docs/cloud/organizations/billing/manage/#upgrading-your-plan) and [Downgrading Your Plan](https://capawesome.io/docs/cloud/organizations/billing/manage/#downgrading-your-plan).

## How do I switch between monthly and yearly billing?

You can switch billing intervals from the Billing page. Yearly plans are paid upfront for 12 months. See [Switching Billing Interval](https://capawesome.io/docs/cloud/organizations/billing/manage/#switching-billing-interval).

## How do I update my billing information?

Open the **Customer portal** from the Billing page to update your company name, billing address, VAT ID, or billing email. See [Billing Details](https://capawesome.io/docs/cloud/organizations/billing/manage/#billing-details).

## What payment methods are accepted?

All major payment methods supported by our Merchant of Record partners, including credit and debit cards. The exact list depends on your country and your provider. See [Payment Methods](https://capawesome.io/docs/cloud/organizations/billing/manage/#payment-methods).

## How do I view and download invoices?

Invoices are available in the Customer Portal of your Merchant of Record. Open it from the Billing page and download any invoice as a PDF. See [Invoices](https://capawesome.io/docs/cloud/organizations/billing/invoices/index.md).

## Why is my invoice from Polar or Lemon Squeezy?

Capawesome uses a Merchant of Record (MoR) model, so [Polar](https://polar.sh/) or [Lemon Squeezy](https://www.lemonsqueezy.com/) is the seller of record for your subscription. They collect payment, charge applicable taxes, and issue your invoice.

## Can I switch from Polar to Lemon Squeezy (or vice versa)?

Yes. New organizations use Polar by default, but you can request a switch to the other provider if you are experiencing payment issues. [Contact support](https://capawesome.io/docs/support/index.md) to request the change.

## Can I get a refund?

Refunds are handled on a case-by-case basis and must be requested through [support](https://capawesome.io/docs/support/index.md).

## How do I contact support for billing issues?

For general billing questions or refund requests, [contact Capawesome support](https://capawesome.io/docs/support/index.md). For corrections to an existing invoice, contact your Merchant of Record directly — either [Polar Support](https://polar.sh/docs/support) or the [Lemon Squeezy Help Center](https://www.lemonsqueezy.com/help).

# Invoices

All invoices, receipts, and payment history for your Capawesome Cloud organization are available in the **Customer portal** of your Merchant of Record — either [Polar](https://polar.sh/) or [Lemon Squeezy](https://www.lemonsqueezy.com/).

## Viewing Payment History

To view your payment history:

1. Go to the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing).
1. Click the button to open the **Customer portal**.
1. Navigate to the invoices or payment history section of the portal.

Only members with the **Owner** or **Billing** role can open the Customer Portal.

## Downloading Invoices and Receipts

From the Customer Portal, you can download each invoice or receipt as a PDF. Open the invoice you need and use the download option provided by the portal.

## Invoice Issuer

Invoices are issued by the Merchant of Record, not by Capawesome directly:

- Organizations on Polar receive invoices from **Polar**.
- Organizations on Lemon Squeezy receive invoices from **Lemon Squeezy**.

This is why the seller name on your invoice is Polar or Lemon Squeezy rather than Capawesome or Genz IT Solutions GmbH.

## Requesting a Corrected Invoice

Capawesome is not able to modify issued invoices. If you need a correction (for example, to update a VAT ID or billing address on a past invoice), you must contact your Merchant of Record directly:

- Polar: [Polar Support](https://polar.sh/docs/support)
- Lemon Squeezy: [Lemon Squeezy Help Center](https://www.lemonsqueezy.com/help)

# Manage Plans & Billing

All plan changes and payment details for your organization are managed from the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing). Only members with the **Owner** or **Billing** role can make changes here.

This page is split into two parts: **Plan Management** covers your subscription, and **Billing Information** covers how you pay.

## Plan Management

### Free Trial

New organizations can start a **14-day free trial** on any paid plan. A valid payment method is required upfront to start the trial. This is to prevent misuse of our Cloud infrastructure and does not result in any charges during the trial period.

When the trial ends, your organization is automatically moved to the selected paid plan and the first invoice is issued. You can cancel at any time during the trial to avoid being charged.

### Viewing Your Current Plan

Your active plan, billing interval, and next renewal date are shown at the top of the Billing page.

### Subscribing to a Plan

To subscribe to a paid plan:

1. Go to the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing).
1. Select either **Monthly** or **Yearly** billing.
1. Choose the plan that best fits your needs.
1. Complete the checkout through Polar or Lemon Squeezy.

For plan details and pricing, see the [pricing page](https://capawesome.io/pricing/).

### Upgrading Your Plan

Upgrades take effect **immediately**. You are invoiced for the new plan right away, and the new features become available as soon as the payment is processed.

### Downgrading Your Plan

Downgrades take effect at the **next renewal date**. You keep access to your current plan until then. The price difference between your old and new plan is **automatically applied as credit** to your upcoming invoice(s) — no action is needed on your side.

### Switching Billing Interval

You can switch between monthly and yearly billing at any time. Yearly plans are **paid upfront for 12 months** and typically come at a discount compared to monthly billing.

Switching to a longer interval takes effect immediately and is invoiced immediately. Switching to a shorter interval takes effect at the next renewal, with any credit applied to upcoming invoices.

### Canceling Your Subscription

To cancel your subscription:

1. Go to the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing).
1. Click **Cancel Subscription** and follow the prompts.

Cancellation takes effect at the **end of the current billing period**. You keep full access to your plan until then, after which your organization is moved to the free tier. You can re-subscribe at any time from the same page.

### Refunds

Refunds are handled on a case-by-case basis and cannot be requested directly from the Billing page. If you believe you are eligible for a refund, please [contact support](https://capawesome.io/docs/support/index.md).

## Billing Information

### Payment Methods

We accept all major payment methods supported by our Merchant of Record partners, including credit and debit cards. The exact list depends on your country and the provider handling your organization.

To update your payment method:

1. Go to the **Billing** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/billing).
1. Click the button to open the **Customer portal** (Polar or Lemon Squeezy).
1. Add or update your payment method directly in the portal.

### Billing Details

Billing details such as company name, billing address, VAT ID, and billing email are managed in the Customer Portal of your provider. Open the Customer Portal from the Billing page to edit them.

Tax (such as VAT or sales tax) is calculated and collected automatically by the Merchant of Record based on your billing address and tax ID.

### Identifying Your Billing Provider

You can tell which provider handles your organization by opening the Customer Portal from the [Billing](https://console.cloud.capawesome.io/organizations/_/billing) page. If the portal shows Polar branding, your organization is on Polar. If it shows Lemon Squeezy branding, your organization is on Lemon Squeezy. All new organizations use Polar by default.

If you are experiencing payment issues with your current provider, you can request a switch to the other provider by [contacting support](https://capawesome.io/docs/support/index.md).

# Single Sign-On (SSO)

Capawesome Cloud supports Single Sign-On (SSO), allowing [organizations](https://capawesome.io/docs/cloud/organizations/index.md) to enforce centralized authentication through their Identity Provider (IdP). With SSO enabled, members of your organization authenticate using your corporate identity management system, providing enhanced security and streamlined access management.

## How SSO Works

SSO relies on a trust relationship between Capawesome Cloud (the Service Provider, or SP) and your organization's Identity Provider (IdP). When SSO is enabled for your organization, members must authenticate through your IdP to access organization resources:

1. A user attempts to access organization resources in Capawesome Cloud.
1. The user is redirected to your Identity Provider's login page.
1. After successful authentication with the IdP, the user is redirected back to Capawesome Cloud.
1. Capawesome Cloud verifies the authentication response and grants access to the organization.

Users are identified by their email address. Make sure that the email address associated with your Identity Provider account matches the email address on your Capawesome Cloud account.

## Supported Protocols

Capawesome Cloud supports SAML 2.0 for Single Sign-On. This means you can integrate with any SAML-compliant Identity Provider, including Azure AD (Microsoft Entra ID), Okta, OneLogin, Google Workspace, PingIdentity, and many others.

## Configuration Guides

We provide step-by-step configuration guides for the following Identity Providers:

| Identity Provider             | Documentation                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| Azure AD (Microsoft Entra ID) | [Configuration Guide](https://capawesome.io/docs/cloud/organizations/sso/azure-saml/index.md) |

If your Identity Provider is not listed above, you can still configure SAML SSO by following the general SAML 2.0 setup process. The required configuration values (Entity ID, Assertion Consumer Service URL, and Sign on URL) are available in your organization's SSO settings.

## Configuring SSO

To configure SSO for your organization:

1. Navigate to your [organization settings](https://console.cloud.capawesome.io/organizations/_/settings) in the Capawesome Cloud Console.
1. Scroll to the **Single Sign-On (SSO)** section.
1. Follow the configuration guide for your Identity Provider.

Only organization owners and admins can configure SSO settings.

## Domain Verification

After configuring SSO, you must verify ownership of your email domain before members can sign in via SSO. This prevents unauthorized SSO provider registration and ensures only domain owners can enable SSO for their domain.

1. After submitting the SSO configuration, click **Verify domain** in the success notification or in the SSO settings section.
1. Add the displayed **TXT** record to your domain's DNS configuration. Most DNS providers auto-append your domain to the host field.
1. Wait for DNS propagation (this can take up to 48 hours, but is typically much faster).
1. Click **Verify** to confirm domain ownership.

Info

SSO sign-in is blocked until domain verification is complete. Members can still sign in with their email and password during this time.

## Sign-In Link

By default, members start SSO from the Capawesome Cloud login screen by entering their email address. Your organization also has a dedicated sign-in link that skips this step and sends members straight to your Identity Provider:

```
https://console.cloud.capawesome.io/sso/sign-in?providerId=YOUR_PROVIDER_ID
```

To copy the link for your organization:

1. Navigate to your [organization settings](https://console.cloud.capawesome.io/organizations/_/settings) in the Capawesome Cloud Console.
1. Scroll to the **Single Sign-On (SSO)** section.
1. Copy the value of the **Sign-in link** field.

You can share this link with your members, publish it on your intranet, or add it to your Identity Provider as an application tile so that members can sign in directly from their IdP dashboard. Most Identity Providers offer this as a bookmark or link application — for example, a **Bookmark** app in OneLogin and Okta, or an application with the **Linked** sign-on mode in Microsoft Entra ID.

Info

The **Sign-in link** field only appears after your domain has been verified, because SSO sign-in is blocked until then.

## User Provisioning

Once SSO is configured and your domain is verified, new users are provisioned automatically — no invitation required. When a user signs in through your Identity Provider with an email address matching your organization's verified SSO domain, Capawesome Cloud will:

1. Create a new user account if one does not already exist.
1. Add the user to your organization with the `member` role.

Organization owners and admins can adjust the user's role afterwards if needed.

Existing users

If a user already has a Capawesome Cloud account with an email that does not match your organization's verified SSO domain, they can enable SSO by updating their email address in their [account settings](https://console.cloud.capawesome.io/settings/account) to one matching the domain. The new email must be verified before SSO sign-in becomes available.

## Requirements

Before configuring SSO, ensure you have:

- An active Capawesome Cloud organization with an appropriate subscription plan.
- Administrator access to your Identity Provider (e.g., Azure AD).
- The ability to create and configure enterprise applications in your IdP.
- Access to your domain's DNS settings for domain verification.

# How to configure SAML SSO with Azure

This guide walks you through configuring SAML-based Single Sign-On (SSO) with Azure AD (Microsoft Entra ID) as your Identity Provider (IdP) for your Capawesome Cloud organization. In this setup, Azure AD acts as the IdP and Capawesome Cloud acts as the Service Provider (SP).

## Prerequisites

Before you begin, ensure you have:

- Administrator access to your organization's [Microsoft Entra admin center](https://entra.microsoft.com)
- Owner or Admin role in your Capawesome Cloud organization

## Step 1: Create an Application in your Identity Provider

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
1. Navigate to **Entra ID** > **Enterprise apps** > **All applications**.
1. Click **New application**.
1. Click **Create your own application**.
1. Enter a name for the application (e.g., `Capawesome Cloud`).
1. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
1. Click **Create**.

## Step 2: Configure your Application

1. In your newly created application, navigate to **Manage** > **Single sign-on**.
1. Select **SAML** as the single sign-on method.

The **Basic SAML Configuration** dialog will appear.

1. Click **Edit** on the **Basic SAML Configuration** section.
1. Open a new browser tab, navigate to your [organization's settings](https://console.cloud.capawesome.io/organizations/_/settings) in the Capawesome Cloud Console, scroll to the **Single Sign-On (SSO)** section, and click **Configure** to view the required URLs.
1. In Capawesome Cloud, copy the **SP Entity ID** and paste it into the **Identifier (Entity ID)** field in Azure.
1. Copy the **Callback URL** from Capawesome Cloud and paste it into the **Reply URL (Assertion Consumer Service URL)** field in Azure.
1. Leave **Sign on URL**, **Relay State** and **Logout URL** empty.
1. Click **Save**.

## Step 3: Configure Attributes and Claims

Azure AD sends user information to Capawesome Cloud through SAML attributes. The default configuration should work for most cases, but verify the following claims are present:

1. Click **Edit** on the **Attributes & Claims** section.
1. Ensure these claims are configured:

| Claim                            | Value            |
| -------------------------------- | ---------------- |
| Unique User Identifier (Name ID) | user.mail        |
| emailaddress                     | user.mail        |
| givenname                        | user.givenname   |
| surname                          | user.surname     |
| name                             | user.displayname |

The **Unique User Identifier (Name ID)** must be set to `user.mail` to properly identify users by their email address.

## Step 4: Complete Configuration in Capawesome Cloud

1. Return to your [organization's SSO settings](https://console.cloud.capawesome.io/organizations/_/settings) in the Capawesome Cloud Console.
1. Enter the **Microsoft Entra Identifier** from Azure AD into the **Issuer** field.
1. Enter the **Login URL** from Azure AD into the **Entry Point** field.
1. Download the **Certificate (Base64)** file from Azure AD, open it in a text editor, and enter the entire certificate content (including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines) into the **Public certificate** field.
1. Enter your domain (e.g., `yourcompany.com`) into the **Domain** field.
1. Click **Configure** to save the SSO configuration.

The certificate should be in PEM format:

```
-----BEGIN CERTIFICATE-----
MIIDp...certificate content...
-----END CERTIFICATE-----
```

## Step 5: Verify Domain Ownership

After configuring SSO, you must verify ownership of your domain before members can sign in via SSO.

1. After submitting the configuration, click **Verify domain** in the success notification or in the SSO settings section.
1. Add the displayed **TXT** record to your domain's DNS configuration. Most DNS providers auto-append your domain to the host field, so you only need to enter the subdomain identifier shown in the **Host** field.
1. Wait for DNS propagation (this can take up to 48 hours, but is typically much faster). You can check propagation status using `dig TXT <host>.<yourdomain.com>`.
1. Click **Verify** to confirm domain ownership.

Once verified, organization members can authenticate through Azure AD to access organization resources.

## Troubleshooting

### AADSTS50011: Reply URL does not match

This error occurs when the Reply URL configured in Azure AD does not match the Assertion Consumer Service URL in Capawesome Cloud.

- Verify that the Reply URL in Azure AD exactly matches the URL shown in your Capawesome Cloud SSO settings.
- Check for trailing slashes or protocol mismatches (http vs https).

### AADSTS700016: Application not found

This error indicates that the application identifier cannot be found in the Azure AD tenant.

- Verify that the Identifier (Entity ID) in Azure AD matches the Entity ID in Capawesome Cloud.
- Ensure the application is properly configured and saved.

### Invalid Signature Error

This error occurs when the certificate validation fails.

- Ensure the certificate is in PEM format (Base64 encoded).
- Verify that the certificate has not expired.
- Check if the certificate has been rotated in Azure AD and update it in Capawesome Cloud if necessary.

### User Not Assigned Error

If a user receives an error stating they are not assigned to the application:

- Verify that the user is assigned to the enterprise application in Azure AD.
- Check group memberships if using group-based assignment.

### Missing or Incorrect User Attributes

If user information is not being correctly transferred:

- Verify the attribute mappings in the **Attributes & Claims** section in Azure AD.
- Ensure the user has the required attributes (email, name) populated in their Azure AD profile.

# Node.js SDK

The official Node.js SDK, [`@capawesome/cloud-sdk`](https://www.npmjs.com/package/@capawesome/cloud-sdk), gives you a fully typed, promise-based interface to the [Capawesome Cloud API](https://capawesome.io/docs/cloud/api/index.md). Use it to manage apps, Live Update channels and deployments, native builds, app store destinations, and more from your own backend or tooling — anywhere the [CLI](https://capawesome.io/docs/cloud/cli/index.md) isn't a fit.

API in development

The Capawesome Cloud API is still evolving and may change without notice. Response types intentionally expose only the most relevant properties to keep breaking changes to a minimum.

## Installation

Install the package from npm. It requires **Node.js 20 or later** and is published as **ESM only**:

```
npm install @capawesome/cloud-sdk
```

## Authentication

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in the Console and pass it to the client. Read it from an environment variable rather than hard-coding it:

```
import { CapawesomeCloud } from "@capawesome/cloud-sdk";

const client = new CapawesomeCloud({
  token: process.env.CAPAWESOME_TOKEN!,
});
```

## Getting started

Most operations are scoped to an app via `appId`, and every method takes a single options object and returns a typed promise:

```
const apps = await client.apps.list({ organizationId: process.env.CAPAWESOME_ORGANIZATION_ID! });
const app = await client.apps.get({ appId });
```

### Configuration

The client accepts a few options beyond the token:

| Option       | Type     | Default                           | Description                                                                    |
| ------------ | -------- | --------------------------------- | ------------------------------------------------------------------------------ |
| `token`      | `string` | —                                 | API token used to authenticate.                                                |
| `baseUrl`    | `string` | `https://api.cloud.capawesome.io` | Base URL of the API.                                                           |
| `timeout`    | `number` | `60000`                           | Request timeout in milliseconds. Does not apply to streamed downloads.         |
| `maxRetries` | `number` | `3`                               | Retries for transient failures (network, `429`, `5xx`) on idempotent requests. |

## Usage

Resources mirror the API's path hierarchy: app-scoped resources are nested under `client.apps.*`, and top-level resources such as `client.jobs` sit directly on the client.

### Trigger a build and wait for it

A native build runs as a background **job**, so trigger it, then poll the job until it finishes:

```
const build = await client.apps.builds.create({
  appId,
  platform: "ios",
  gitRef: "main",
});

let job = await client.jobs.get({ jobId: build.jobId! });
while (job.status === "queued" || job.status === "pending" || job.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  job = await client.jobs.get({ jobId: job.id });
}
```

### Promote a build to a channel

Create a deployment to publish a build to a Live Update channel — optionally as a gradual rollout:

```
const deployment = await client.apps.deployments.create({
  appId,
  appBuildId,
  appChannelName: "production",
  rolloutPercentage: 0.5,
});
```

### Submit a build to a store

Create a deployment to a [destination](https://capawesome.io/docs/cloud/app-store-publishing/destinations/index.md) to submit a native build to a store, optionally with [release notes](https://capawesome.io/docs/cloud/app-store-publishing/release-notes/index.md) and their translations by locale:

```
const deployment = await client.apps.deployments.create({
  appId,
  appBuildId,
  appDestinationName: "Google Play",
  releaseNotes: {
    default: "Bug fixes and performance improvements.",
    "de-DE": "Fehlerbehebungen und Leistungsverbesserungen.",
  },
});
```

`builds.create()` accepts the same `releaseNotes` option together with `appDestinationId`, so the build is submitted with its release notes once it finishes.

### Download a build artifact

Binary downloads return a `ReadableStream`, so large files stream straight to disk without buffering in memory:

```
import { Writable } from "node:stream";
import { createWriteStream } from "node:fs";

const stream = await client.apps.builds.artifacts.download({ appId, buildId, artifactId });
await stream.pipeTo(Writable.toWeb(createWriteStream("artifact.ipa")));
```

## Error handling

Any non-`2xx` response is thrown as a `CapawesomeCloudError` carrying the status code, message, and raw body:

```
import { CapawesomeCloudError } from "@capawesome/cloud-sdk";

try {
  await client.apps.get({ appId: "unknown" });
} catch (error) {
  if (error instanceof CapawesomeCloudError) {
    console.error(error.status); // 404
    console.error(error.message); // "App not found."
  }
}
```

## Reference

The SDK covers the full API surface — apps, channels, deployments, builds and artifacts, certificates, environments, automations, devices, webhooks, and jobs. For the complete list of resources and options, see the [package on npm](https://www.npmjs.com/package/@capawesome/cloud-sdk) and the [source on GitHub](https://github.com/capawesome-team/cloud-node), or browse the underlying [Cloud API](https://capawesome.io/docs/cloud/api/index.md).

# Python SDK

The official Python SDK, [`capawesome-cloud`](https://pypi.org/project/capawesome-cloud/), gives you a fully typed, synchronous interface to the [Capawesome Cloud API](https://capawesome.io/docs/cloud/api/index.md). Use it to manage apps, Live Update channels and deployments, native builds, app store destinations, and more from your own backend or tooling — anywhere the [CLI](https://capawesome.io/docs/cloud/cli/index.md) isn't a fit.

API in development

The Capawesome Cloud API is still evolving and may change without notice. Response types intentionally expose only the most relevant properties to keep breaking changes to a minimum.

## Installation

Install the package from PyPI. It requires **Python 3.9 or later**:

```
pip install capawesome-cloud
```

## Authentication

Create an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) in the Console and pass it to the client, or set the `CAPAWESOME_CLOUD_TOKEN` environment variable (with `CAPAWESOME_TOKEN` accepted as a fallback):

```
from capawesome_cloud import CapawesomeCloud

client = CapawesomeCloud(token="cap_...")
```

The client holds a connection pool, so reuse a single instance. Use it as a context manager — or call `client.close()` — to release connections when you're done:

```
with CapawesomeCloud(token="cap_...") as client:
    for app in client.apps.list():
        print(app.id, app.name)
```

### Configuration

The client accepts a few options beyond the token:

| Option        | Type           | Default                           | Description                                                                                                                |
| ------------- | -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `token`       | `str`          | `CAPAWESOME_CLOUD_TOKEN` env var  | API token used to authenticate.                                                                                            |
| `base_url`    | `str`          | `https://api.cloud.capawesome.io` | Base URL of the API.                                                                                                       |
| `timeout`     | `float`        | `30.0`                            | Request timeout in seconds.                                                                                                |
| `max_retries` | `int`          | `2`                               | Retries with exponential backoff. `429` is always retried; network/`5xx` failures are retried only for idempotent methods. |
| `http_client` | `httpx.Client` | `None`                            | Bring your own pre-configured `httpx.Client`.                                                                              |

## Usage

Resources mirror the API's path hierarchy: app-scoped resources are nested under `client.apps.*` and take `app_id` as their first argument, while top-level resources such as `client.jobs` sit directly on the client.

### Trigger a build and wait for it

A native build runs as a background **job**. Trigger it, then use the `wait()` helper to block until the job finishes:

```
build = client.apps.builds.create(app_id, platform="ios", git_ref="main")

job = client.jobs.wait(build.job_id)
print(job.status)
```

### Promote a build to a channel

Create a deployment to publish a build to a Live Update channel — optionally as a gradual rollout:

```
deployment = client.apps.deployments.create(
    app_id,
    app_build_id=app_build_id,
    app_channel_name="production",
    rollout_percentage=0.5,
)
```

### Pagination

List methods return an iterator that lazily pages through **all** results. Iterate it directly, or collect everything with `to_list()`:

```
for device in client.apps.devices.list(app_id):
    print(device.id, device.app_version_name)

channels = client.apps.channels.list(app_id).to_list()
```

To fetch a single page with manual offset control, use `list_page()`:

```
page = client.apps.channels.list_page(app_id, limit=20, offset=0)
```

## Responses

Responses are typed [Pydantic](https://docs.pydantic.dev) models, with app-scoped models prefixed `App` (`AppChannel`, `AppBuild`, …) to match the API's entity names. Only the most relevant fields are part of the public contract; any extra fields the API returns are still accessible via `model_dump()` but shouldn't be relied upon:

```
channel = client.apps.channels.get(app_id, channel_id)
print(channel.name, channel.created_at)   # documented fields
print(channel.model_dump())               # full raw payload
```

## Reference

The SDK covers the full API surface — apps, channels, deployments, builds and artifacts, certificates, environments, automations, devices, webhooks, and jobs. For the complete list of resources and options, see the [package on PyPI](https://pypi.org/project/capawesome-cloud/) and the [source on GitHub](https://github.com/capawesome-team/cloud-python), or browse the underlying [Cloud API](https://capawesome.io/docs/cloud/api/index.md).

# Webhooks

Webhooks let you receive real-time notifications when events occur in your app. When an event is triggered, Capawesome Cloud sends an HTTP `POST` request to your configured endpoint — enabling integrations with CI/CD pipelines, chat tools, or custom backends.

Outbound vs inbound

These are **outbound** webhooks (Capawesome Cloud → your endpoint). They are not the same as the inbound Git webhook used by [Automations](https://capawesome.io/docs/cloud/automations/webhooks/index.md) to receive events from your Git provider.

## Formats

Each webhook has a **format** that controls the payload:

- **Raw** — a JSON payload for custom integrations and backends. Supports [signing](https://capawesome.io/docs/cloud/webhooks/securing/index.md) for verification.
- **Notification formats** — pre-formatted messages for [Slack](https://capawesome.io/docs/cloud/integrations/slack/index.md), [Discord](https://capawesome.io/docs/cloud/integrations/discord/index.md), and [Microsoft Teams](https://capawesome.io/docs/cloud/integrations/microsoft-teams/index.md).

## Documentation

- [Get Started](https://capawesome.io/docs/cloud/webhooks/setup/index.md) — create a webhook and receive your first event.
- [Event Types](https://capawesome.io/docs/cloud/webhooks/event-types/index.md) — the events you can subscribe to.
- [Payload Structure](https://capawesome.io/docs/cloud/webhooks/payload-structure/index.md) — the shape of the JSON payload.
- [Securing Webhooks](https://capawesome.io/docs/cloud/webhooks/securing/index.md) — verify signatures.
- [Delivery & Retries](https://capawesome.io/docs/cloud/webhooks/delivery-and-retries/index.md) — delivery history and resending.
- [Best Practices](https://capawesome.io/docs/cloud/webhooks/best-practices/index.md).

## Bonus: Video Walkthrough

# Best Practices

A few patterns make your webhook endpoint reliable:

- **Respond `2xx` quickly, process asynchronously.** Acknowledge the request as soon as you've received it, then do any slow work (notifications, database writes) in the background. Slow endpoints risk being marked as failed.
- **Verify the signature.** Configure a signing secret and [verify the `X-Signature`](https://capawesome.io/docs/cloud/webhooks/securing/index.md) on every request so you only act on authentic payloads.
- **Handle duplicates.** Treat deliveries as at-least-once: a resend or retry can deliver the same event more than once. Use the event's `id` to make your processing idempotent.
- **Use the right format.** For chat notifications, use the [Slack](https://capawesome.io/docs/cloud/integrations/slack/index.md), [Discord](https://capawesome.io/docs/cloud/integrations/discord/index.md), or [Microsoft Teams](https://capawesome.io/docs/cloud/integrations/microsoft-teams/index.md) format instead of parsing `Raw` yourself.
- **Inspect failures.** When something goes wrong, the [delivery log](https://capawesome.io/docs/cloud/webhooks/delivery-and-retries/index.md) shows the exact request and response so you can debug and resend.

# Delivery & Retries

Every webhook keeps a **delivery log** so you can see exactly what was sent and how your endpoint responded.

Each delivery record includes:

- **Event** — the event that triggered the delivery.
- **Payload** — the JSON payload sent to your endpoint.
- **Response status** — the HTTP status your endpoint returned.
- **Response body** — the response body your endpoint returned.
- **Sent** — the timestamp of the delivery attempt.

A delivery is marked **successful** when your endpoint responds with a `2xx` status code. Failed deliveries can be **manually resent** from the [Console](https://console.cloud.capawesome.io/).

Respond quickly

Return a `2xx` response as soon as you've received the payload, and do any heavy processing asynchronously — see [Best practices](https://capawesome.io/docs/cloud/webhooks/best-practices/index.md).

# Event Types

When you create a webhook, you subscribe it to one or more events. Capawesome Cloud then sends a request each time one of those events occurs.

The following events are currently supported:

| Event                    | Fires when                                       |
| ------------------------ | ------------------------------------------------ |
| `app_build_created`      | A new app build is created.                      |
| `app_deployment_created` | A new deployment is created.                     |
| `job_created`            | A new job is created.                            |
| `job_finished`           | A job finishes (succeeded, failed, or canceled). |

## Resource events vs. job events

It helps to know the difference between the two kinds of events:

- **Resource events** (`app_build_created`, `app_deployment_created`) fire the moment a build or deployment is *created* — useful to know that work has started.
- **Job events** (`job_created`, `job_finished`) track the *execution* behind that work. Every build and deployment runs as a job, so `job_finished` is the event to subscribe to when you care about the outcome — its payload carries the final `status` and links back to the build or deployment via `appBuildId` / `appDeploymentId`.

In practice, most integrations subscribe to `job_finished` to react to a build or deployment succeeding or failing.

The request body for every event follows the same envelope — see [Payload structure](https://capawesome.io/docs/cloud/webhooks/payload-structure/index.md).

Need an event that's not listed here? [Let us know](https://capawesome.io/docs/support/index.md) and we'll look into adding it.

# Payload Structure

Every webhook request (using the `Raw` format) contains a JSON body with two top-level fields:

- `event` — the [event type](https://capawesome.io/docs/cloud/webhooks/event-types/index.md) that triggered the request.
- `data` — the event payload.

Here is an example of a `job_finished` event:

```
{
  "event": "job_finished",
  "data": {
    "id": "16555c02-a320-4bec-a14a-52754d783970",
    "appBuildId": "647d1fe4-9cb7-4f25-afaf-7a0c13a1bb8c",
    "appDeploymentId": null,
    "appId": "70922e93-0944-48cc-a560-61135ab291ad",
    "finishedAt": 1771143284003,
    "inProgressAt": 1771143275311,
    "inProgressTimeInSeconds": 8,
    "organizationId": "a7249949-a705-4952-a293-a06df84950dc",
    "pendingAt": 1771143256381,
    "queuedAt": null,
    "stack": "macos-tahoe",
    "status": "canceled",
    "totalTimeInSeconds": 27,
    "createdAt": 1771143256161,
    "createdBy": "f624e455-b19c-4f17-8282-e4a7a02597f3"
  }
}
```

## Reading the payload

The exact fields inside `data` depend on the event type, but a few conventions hold across all of them:

- **IDs are UUIDs.** Fields like `id`, `appId`, and `organizationId` identify the resource and let you correlate the event with what you already know.
- **Timestamps are Unix epoch milliseconds.** Lifecycle fields such as `queuedAt`, `pendingAt`, `inProgressAt`, and `finishedAt` mark each stage; a `null` means that stage didn't occur (here, the job was canceled before it queued).
- **`status` carries the outcome** of a finished job — for example `succeeded`, `failed`, or `canceled` — which is usually the field your integration branches on.
- **Related resources are linked by ID.** A job points back to its build or deployment via `appBuildId` / `appDeploymentId`; the unused one is `null`.

Always switch on the top-level `event` first, then read the `data` fields that apply to that event.

To make sure a request really came from Capawesome Cloud, [verify its signature](https://capawesome.io/docs/cloud/webhooks/securing/index.md).

# Securing Webhooks

Your webhook endpoint is a public URL, so anyone who discovers it could send it a forged request. Signing fixes that: when a webhook has a **signing secret** configured (available for the `Raw` format), Capawesome Cloud signs every request so your endpoint can confirm it's genuine.

You set the signing secret when you [create or edit the webhook](https://capawesome.io/docs/cloud/webhooks/setup/index.md). With it in place, each request includes an `X-Signature` header containing an HMAC-SHA256 signature of the raw request body. Verify this signature on your endpoint to ensure the request is authentic and hasn't been tampered with.

Two details matter for the check to be correct:

- Always compute the HMAC over the **raw request body** — the exact bytes you received, not a re-serialized object, since reserializing can change whitespace or key order and break the signature.
- Use a **constant-time comparison** to avoid leaking information through timing.

```
import crypto from "node:crypto";

const secret = "SIGNING_SECRET";
const digest = Buffer.from(
  crypto.createHmac("sha256", secret).update(request.rawBody).digest("hex"),
  "utf8"
);
const signature = Buffer.from(request.get("X-Signature") || "", "utf8");

if (digest.length !== signature.length || !crypto.timingSafeEqual(digest, signature)) {
  throw new Error("Invalid signature.");
}
```

```
import hashlib
import hmac

secret = b"SIGNING_SECRET"
digest = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
signature = request.headers.get("X-Signature", "")

if not hmac.compare_digest(digest, signature):
    raise ValueError("Invalid signature.")
```

If the signatures don't match, reject the request — return a `4xx` and don't process the payload.

# Getting Started

Webhooks are configured per app. To create one, open **Settings → Webhooks** in your app's sidebar in the [Console](https://console.cloud.capawesome.io/) and click **Create**.

Each webhook has the following properties:

- **Name** (required) — a human-readable name to identify the webhook.
- **URL** (required) — the endpoint that receives the `POST` requests.
- **Format** (required) — `Raw` for custom integrations, or a notification format ([Slack](https://capawesome.io/docs/cloud/integrations/slack/index.md), [Discord](https://capawesome.io/docs/cloud/integrations/discord/index.md), [Microsoft Teams](https://capawesome.io/docs/cloud/integrations/microsoft-teams/index.md)).
- **Events** (required) — one or more [events](https://capawesome.io/docs/cloud/webhooks/event-types/index.md) that trigger the webhook.
- **Signing secret** (optional) — a secret used to [sign each request](https://capawesome.io/docs/cloud/webhooks/securing/index.md) so the receiver can verify authenticity. Only available for the `Raw` format.

Choosing a **format** is the main decision here: pick a notification format when you just want messages in a chat channel, or `Raw` when your own backend needs to react to the event — in which case you'll also want a signing secret to [verify each request](https://capawesome.io/docs/cloud/webhooks/securing/index.md).

Test before going live

Use [webhook.cool](https://webhook.cool/) to generate a temporary URL and inspect real payloads before pointing the webhook at your production endpoint.

Once created, trigger one of the subscribed [events](https://capawesome.io/docs/cloud/webhooks/event-types/index.md) — for example, by starting a build — and confirm your endpoint receives the request. Every attempt is recorded in the [delivery log](https://capawesome.io/docs/cloud/webhooks/delivery-and-retries/index.md), so you can see exactly what was sent and how your endpoint responded.

## Next steps

- [Event Types](https://capawesome.io/docs/cloud/webhooks/event-types/index.md) — the events you can subscribe to.
- [Payload Structure](https://capawesome.io/docs/cloud/webhooks/payload-structure/index.md) — the shape of the JSON your endpoint receives.
- [Securing Webhooks](https://capawesome.io/docs/cloud/webhooks/securing/index.md) — verify requests with a signing secret.
# Insiders

# Capawesome Insiders

Capawesome Insiders is a subscription that gives you access to **premium, production-ready SDKs** that aren't part of the open-source distribution, plus priority support. They're built and maintained by official Ionic Developer Experts and licensed under the [Capawesome Insider License](/legal/eula/) for commercial and non-commercial use. Insiders replaced our earlier [sponsorware model](https://capawesome.io/blog/capawesome-insiders-goals-changes/index.md) with stable, predictable access to new SDKs.

To learn about pricing and see customer stories, visit the [Insiders landing page](https://capawesome.io/insiders/).

## What you get

- **Immediate access** to all Insider SDKs the moment you subscribe.
- **Regular updates** for new OS versions, security patches, and features.
- **Priority support** from official Ionic Developer Experts.
- New SDKs added regularly.

## Available SDKs

### Hardware & Sensors

- [**Accelerometer**](https://capawesome.io/docs/sdks/capacitor/accelerometer/index.md) — device acceleration and motion
- [**Barometer**](https://capawesome.io/docs/sdks/capacitor/barometer/index.md) — atmospheric pressure
- [**Pedometer**](https://capawesome.io/docs/sdks/capacitor/pedometer/index.md) — step and walking activity
- [**Bluetooth Low Energy**](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) — connect to BLE devices
- [**NFC**](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) — read, write, and emulate NFC tags
- [**Wifi**](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) — manage WiFi connections
- [**Zeroconf**](https://capawesome.io/docs/sdks/capacitor/zeroconf/index.md) — discover services on the local network
- [**Health**](https://capawesome.io/docs/sdks/capacitor/health/index.md) — read and write health and workout data

### Authentication & Security

- [**Biometrics**](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) — face and fingerprint authentication
- [**OAuth**](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) — OAuth 2.0 and OpenID Connect
- [**Secure Preferences**](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) — encrypted key-value storage
- [**Vault**](https://capawesome.io/docs/sdks/capacitor/vault/index.md) — lockable, biometric-protected vaults

### Media & Audio

- [**Audio Player**](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) — playback with background support
- [**Audio Recorder**](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) — high-quality recording
- [**Media Session**](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) — media controls and metadata
- [**Speech Recognition**](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) — speech-to-text
- [**Speech Synthesis**](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) — text-to-speech

### Scanning

- [**Barcode Scanner**](https://capawesome.io/docs/sdks/capacitor/barcode-scanner/index.md) — scan barcodes and QR codes
- [**Document Scanner**](https://capawesome.io/docs/sdks/capacitor/document-scanner/index.md) — scan documents to JPEG or PDF

### Data & Files

- [**Contacts**](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) — read, write, and select contacts
- [**File Compressor**](https://capawesome.io/docs/sdks/capacitor/file-compressor/index.md) — compress and decompress files
- [**File Manager**](https://capawesome.io/docs/sdks/capacitor/file-manager/index.md) — read, write, and move files and directories
- [**File Transfer**](https://capawesome.io/docs/sdks/capacitor/file-transfer/index.md) — upload and download with progress
- [**SQLite**](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) — local database
- [**Zip**](https://capawesome.io/docs/sdks/capacitor/zip/index.md) — create and extract ZIP archives

### Location

- [**Background Geolocation**](https://capawesome.io/docs/sdks/capacitor/background-geolocation/index.md) — track location in the background
- [**Geofences**](https://capawesome.io/docs/sdks/capacitor/geofences/index.md) — monitor circular regions

### Utilities

- [**AdMob**](https://capawesome.io/docs/sdks/capacitor/admob/index.md) — banner, interstitial, and rewarded ads
- [**Calendar**](https://capawesome.io/docs/sdks/capacitor/calendar/index.md) — read and write calendars and events
- [**Geocoder**](https://capawesome.io/docs/sdks/capacitor/geocoder/index.md) — geocoding and reverse geocoding
- [**LLM**](https://capawesome.io/docs/sdks/capacitor/llm/index.md) — on-device AI with Gemini Nano and Apple Intelligence
- [**Printer**](https://capawesome.io/docs/sdks/capacitor/printer/index.md) — print documents and images
- [**Purchases**](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) — in-app purchases and subscriptions
- [**Share Target**](https://capawesome.io/docs/sdks/capacitor/share-target/index.md) — receive shared content
- [**Watch**](https://capawesome.io/docs/sdks/capacitor/watch/index.md) — message Apple Watch and Wear OS apps

## Become an Insider

1. Choose a plan on the [pricing page](https://capawesome.io/pricing/).
1. Follow [Getting Started](https://capawesome.io/docs/insiders/getting-started/index.md) to configure the private registry with your [license key](https://capawesome.io/docs/cloud/license-keys/index.md), or see [Integrations](https://capawesome.io/docs/insiders/integrations/index.md) to set it up in your CI/CD pipeline or build platform.

After subscribing, manage your license keys in the [Console](https://console.cloud.capawesome.io/organizations/_/license-keys). Existing customers can use the [Polar Customer Portal](https://polar.sh/capawesome-team/portal). See [Billing & Plans](https://capawesome.io/docs/insiders/billing-and-plans/index.md) for subscription management.

# Billing & Plans

Capawesome Insiders is a subscription that unlocks premium SDKs and priority support. Compare plans on the [pricing page](https://capawesome.io/pricing/).

## Manage your subscription

Subscriptions are managed through Capawesome Cloud. Open the [Console](https://console.cloud.capawesome.io) to upgrade, downgrade, change your billing interval, or cancel. See [Billing](https://capawesome.io/docs/cloud/organizations/billing/index.md) for details on managing plans, payment methods, and invoices.

Existing customers

If you subscribed via Polar before billing moved to Capawesome Cloud, you can manage your subscription in the [Polar Customer Portal](https://polar.sh/capawesome-team/portal).

## Access

Your Insiders subscription grants access to the private package registry via a [license key](https://capawesome.io/docs/cloud/license-keys/index.md). See [Getting Started](https://capawesome.io/docs/insiders/getting-started/index.md) to set it up.

## Cancellation

You can cancel anytime. If you cancel, you lose access to the private registry and the Insiders SDKs at the end of your billing period. See the [FAQ](https://capawesome.io/docs/insiders/faq/index.md) for details.

# FAQ

## Access

### Where can I find my license key?

If you subscribed via Capawesome Cloud, manage your license keys in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys). See [License keys](https://capawesome.io/docs/cloud/license-keys/index.md) for details.

Existing customers who subscribed via Polar can find their license key in the [Polar Customer Portal](https://polar.sh/capawesome-team/portal). Log in with the email address you used to subscribe and copy the key from the "License Keys" section.

### What happens if I cancel my subscription?

If you cancel your subscription, you will lose access to the private npm registry and the plugins that are part of Insiders.

## Billing and Payment

### How can I cancel my subscription?

Capawesome Cloud subscribers can cancel from the [Capawesome Cloud Console](https://console.cloud.capawesome.io).

Existing Polar customers can cancel anytime in the [Polar Customer Portal](https://polar.sh/capawesome-team/portal) by clicking the "Unsubscribe" button.

# Getting started with Insiders

Welcome to Capawesome Insiders! You've joined **500+ development teams** who trust our plugins to build production apps. You now have access to 34+ professional Capacitor plugins that will save you weeks of development time.

## What You Get

As an Insider, you get immediate access to:

- **Full source code** for all 34+ Insider plugins (1M+ downloads/month)
- **Complete documentation** with examples and guides
- **Priority support** from official Ionic Developer Experts (tier-dependent)
- **Regular updates** for new OS versions and features
- **Breaking change support** and migration guides
- **New plugins** added every other month

[Browse all available plugins](https://capawesome.io/docs/insiders/#available-sdks)

## Retrieve Your License Key

License keys grant access to the private npm registry that hosts the Insider plugins. How you retrieve your key depends on how you subscribed:

**Capawesome Cloud subscribers** — Manage license keys in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys). See [License keys](https://capawesome.io/docs/cloud/license-keys/index.md) for details on creating, rotating, and managing keys.

**Existing Polar customers** — Your license key is available in the [Polar Customer Portal](https://polar.sh/capawesome-team/portal). Log in with the email address used for your subscription and copy the key from the "License Keys" section.

**Keep your license key secure** — it provides access to the private npm registry.

## Quick Start

Get started in under 2 minutes. Follow these steps to install your first Insider plugin:

### Step 1: Configure npm Registry

Configure npm to use the Capawesome private registry:

```
npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>
```

Replace the placeholder

Replace `<YOUR_LICENSE_KEY>` with your actual license key from the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys) or, for existing customers, the [Polar Customer Portal](https://polar.sh/capawesome-team/portal).

### Step 2: Install a Plugin

Install any Insider plugin using npm:

```
npm install @capawesome-team/<plugin-name>
npx cap sync
```

**Example:** To install the NFC plugin:

```
npm install @capawesome-team/capacitor-nfc
npx cap sync
```

### Step 3: Import and Use

Import the plugin in your code and start using it:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

// Start using the plugin
const result = await Nfc.isSupported();
console.log('NFC supported:', result.isSupported);
```

That's it! Check each plugin's documentation for detailed API reference and examples.

## What's Next?

- **Explore Plugins**

  ______________________________________________________________________

  Browse the complete list of available Insider plugins and their capabilities.

  [View all plugins](https://capawesome.io/docs/insiders/#available-plugins)

- **Read Documentation**

  ______________________________________________________________________

  Each plugin has comprehensive documentation with examples and API reference.

  [Plugin documentation](https://capawesome.io/docs/sdks/capacitor/index.md)

- **Get Support**

  ______________________________________________________________________

  Need help? Access priority support via GitHub, Discord, or Email.

  [Learn about support](https://capawesome.io/docs/support/index.md)

- **CI/CD Setup**

  ______________________________________________________________________

  Set up Insider plugins in your CI/CD pipeline for automated builds.

  [View integrations](#cicd-configuration)

______________________________________________________________________

## CI/CD Configuration

Using Insider plugins in your CI/CD pipeline requires configuring the private npm registry with your license key. We provide step-by-step guides for popular platforms:

- **GitHub Actions**

  ______________________________________________________________________

  Configure GitHub Actions to access Insider plugins in your workflows.

  [View guide](https://capawesome.io/docs/insiders/integrations/github-actions/index.md)

- **GitLab CI/CD**

  ______________________________________________________________________

  Set up GitLab CI/CD pipelines with Insider plugin access.

  [View guide](https://capawesome.io/docs/insiders/integrations/gitlab-ci/index.md)

- **Azure DevOps**

  ______________________________________________________________________

  Configure Azure Pipelines for Insider plugin builds.

  [View guide](https://capawesome.io/docs/insiders/integrations/azure-devops/index.md)

- **Bitbucket Pipelines**

  ______________________________________________________________________

  Enable Insider plugins in Bitbucket CI/CD.

  [View guide](https://capawesome.io/docs/insiders/integrations/bitbucket-pipelines/index.md)

- **Ionic Appflow**

  ______________________________________________________________________

  Use Insider plugins with Ionic's cloud build service.

  [View guide](https://capawesome.io/docs/insiders/integrations/ionic-appflow/index.md)

- **Vercel**

  ______________________________________________________________________

  Deploy apps using Insider plugins on Vercel.

  [View guide](https://capawesome.io/docs/insiders/integrations/vercel/index.md)

- **Cloudflare Pages**

  ______________________________________________________________________

  Build and deploy with Insider plugins on Cloudflare.

  [View guide](https://capawesome.io/docs/insiders/integrations/cloudflare-pages/index.md)

- **AWS Amplify**

  ______________________________________________________________________

  Configure AWS Amplify for Insider plugin builds.

  [View guide](https://capawesome.io/docs/insiders/integrations/aws-amplify/index.md)

- **Jenkins**

  ______________________________________________________________________

  Set up Jenkins pipelines with Insider plugin access.

  [View guide](https://capawesome.io/docs/insiders/integrations/jenkins/index.md)

______________________________________________________________________

## Troubleshooting

### Common Issues

**Authentication failed when installing plugins:**

- Verify your license key is correct in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/license-keys) or the [Polar Customer Portal](https://polar.sh/capawesome-team/portal)
- Ensure you've configured both npm registry settings (registry URL and auth token)
- Check that your subscription is active

**Plugin not found:**

- Make sure you're using the correct package name: `@capawesome-team/<plugin-name>`
- Verify your license hasn't expired (for perpetual licenses)

**Need more help?**

Contact our support team at [support@capawesome.io](mailto:support@capawesome.io) or visit our [support page](https://capawesome.io/docs/support/index.md) for priority assistance.

## Bonus: Video Walkthrough

Prefer to watch? This walkthrough covers getting started with Capawesome Insiders:

# Integrations

Integrate Capawesome Insiders with your CI/CD pipeline, build platform, or mobile build service to install the private Capawesome npm packages in your workflows.

## CI/CD

- **Azure DevOps**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Azure DevOps pipelines.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/azure-devops/index.md)

- **Bitbucket Pipelines**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Bitbucket Pipelines.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/bitbucket-pipelines/index.md)

- **GitHub Actions**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your GitHub Actions workflows.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/github-actions/index.md)

- **GitLab CI/CD**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your GitLab CI/CD pipelines.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/gitlab-ci/index.md)

- **Jenkins**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Jenkins pipelines.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/jenkins/index.md)

## Build Platforms

- **AWS Amplify**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your AWS Amplify deployments.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/aws-amplify/index.md)

- **Cloudflare Pages**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Cloudflare Pages builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/cloudflare-pages/index.md)

- **Vercel**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Vercel deployments.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/vercel/index.md)

## Mobile Build Services

- **Capawesome Cloud**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Capawesome Cloud builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/capawesome-cloud/index.md)

- **Ionic Appflow**

  ______________________________________________________________________

  Install Capawesome Insiders packages in your Ionic Appflow builds.

  ______________________________________________________________________

  [Learn more](https://capawesome.io/docs/insiders/integrations/ionic-appflow/index.md)

# AWS Amplify

You can use private Capawesome npm packages within your [AWS Amplify](https://aws.amazon.com/amplify/) deployments by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create an AWS Amplify Environment Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your AWS Amplify app as an environment variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/setting-env-vars.html).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Configuration

### Configure the amplify.yml file

Create or update the `amplify.yml` file in the root of your project and add the following commands to the `preBuild` phase:

```
- echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
- echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during AWS Amplify builds.

### Example

Here's a complete example of an `amplify.yml` file for a project using private Capawesome packages:

```
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
        - echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
```

# Azure DevOps

You can use private Capawesome npm packages within your [Azure Pipelines](https://azure.microsoft.com/products/devops/pipelines) by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create an Azure Pipeline Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Azure Pipeline as a secret variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Set secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables). Make sure to mark the variable as secret.

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Pipeline Configuration

### Configure the npm registry

Add the following script steps to your Azure Pipeline **before** installing npm dependencies:

```
- script: echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
  displayName: Configure Capawesome npm registry
- script: echo "//npm.registry.capawesome.io/:_authToken=$(CAPAWESOME_NPM_REGISTRY_TOKEN)" >> .npmrc
  displayName: Authenticate with Capawesome registry
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Azure DevOps builds.

### Example

Here's a complete example of an `azure-pipelines.yml` file that builds an Ionic app using private Capawesome packages:

```
trigger:
- main

pool:
  vmImage: ubuntu-latest

variables:
  - name: nodeVersion
    value: '20.x'

jobs:
- job: Build
  displayName: Build App
  steps:
  - checkout: self
    displayName: Checkout Repository
  - task: UseNode@1
    inputs:
      version: $(nodeVersion)
    displayName: Setup Node.js $(nodeVersion)
  - script: echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
    displayName: Configure Capawesome npm registry
  - script: echo "//npm.registry.capawesome.io/:_authToken=$(CAPAWESOME_NPM_REGISTRY_TOKEN)" >> .npmrc
    displayName: Authenticate with Capawesome registry
  - script: npm ci
    displayName: Install Dependencies
  - script: npx cap sync
    displayName: Sync Capacitor
  - script: npm run build
    displayName: Build App
  - task: PublishBuildArtifacts@1
    inputs:
      pathtoPublish: 'dist'
      artifactName: 'build-output'
    displayName: Publish Build Artifacts
```

# Bitbucket Pipelines

You can use private Capawesome npm packages within your [Bitbucket Pipelines](https://www.atlassian.com/software/bitbucket/features/pipelines) builds by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a Bitbucket Repository Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Bitbucket repository as a secured repository variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Variables and secrets](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/). Make sure to mark the variable as secured.

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Pipeline Configuration

### Configure the npm registry

Add the following script to your Bitbucket Pipeline **before** installing npm dependencies:

```
- echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
- echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Bitbucket Pipelines builds.

### Example

Here's a complete example of a `bitbucket-pipelines.yml` file that builds an Ionic app using private Capawesome packages:

```
image: node:20

pipelines:
  default:
    - step:
        name: Build App
        caches:
          - node
        script:
          - echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
          - echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
          - npm ci
          - npx cap sync
          - npm run build
        artifacts:
          - dist/**
```

# Capawesome Cloud

You can use private Capawesome npm packages within your [Capawesome Cloud](/) builds by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a Capawesome Cloud Environment Secret

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Capawesome Cloud app as an environment secret with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Add variables and secrets](https://capawesome.io/docs/cloud/native-builds/environments/#add-variables-and-secrets).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Configuration

### Configure the npm registry

Create a new file named `.npmrc` in the root of your project and add the following content:

```
@capawesome-team:registry=https://npm.registry.capawesome.io
//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}
```

This file will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Capawesome Cloud builds.

### Managing multiple environments

In the event that your local development no longer works with your new `.npmrc` file, you can create a separate `.npmrc.capawesome` file specifically for Capawesome Cloud. Just open the [Environments](https://console.cloud.capawesome.io/apps/_/environments) page, choose **Manage environment variables** from your environment's actions menu, add a new environment variable named `NPM_CONFIG_USERCONFIG` and set its value to `/tmp/capawesome/repo/.npmrc.capawesome`. If your `.npmrc.capawesome` file is not in your project's root directory, adjust this path accordingly.

# Cloudflare Pages

You can use private Capawesome npm packages within your [Cloudflare Pages](https://pages.cloudflare.com/) deployments by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a Cloudflare Pages Environment Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Cloudflare Pages project as an environment variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Environment variables](https://developers.cloudflare.com/pages/configuration/build-configuration/#environment-variables).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Configuration

### Configure the npm registry

Create a new file named `.npmrc` in the root of your project and add the following content:

```
@capawesome-team:registry=https://npm.registry.capawesome.io
//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}
```

This file will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Cloudflare Pages builds.

### Managing multiple environments

In the event that your local development no longer works with your new `.npmrc` file, you can create a separate `.npmrc.pages` file specifically for Cloudflare Pages. Just navigate to your **Pages project > Settings > Environment variables**, add a new environment variable named `NPM_CONFIG_USERCONFIG` and set its value to `/opt/buildhome/repo/.npmrc.pages`. If your `.npmrc.pages` file is not in your project's root directory, adjust this path accordingly.

# GitHub Actions

You can use private Capawesome npm packages within your [GitHub Actions](https://github.com/features/actions) workflows by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a GitHub Secret

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your GitHub repository as an encrypted secret with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Creating encrypted secrets for a repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-encrypted-secrets-for-a-repository).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Workflow Configuration

### Configure the npm registry

Add the following step to your GitHub Actions workflow **before** installing npm dependencies:

```
- name: Configure the Capawesome npm registry
  run: |
    echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
    echo "//npm.registry.capawesome.io/:_authToken=${{ secrets.CAPAWESOME_NPM_REGISTRY_TOKEN }}" >> .npmrc
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during GitHub Actions builds.

### Example

Here's a complete example of a GitHub Actions workflow that builds an Ionic app using private Capawesome packages:

```
name: Build App

on:
  push:
    branches: 
      - main
  pull_request:
    branches: 
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Configure the Capawesome npm registry
        run: |
          echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
          echo "//npm.registry.capawesome.io/:_authToken=${{ secrets.CAPAWESOME_NPM_REGISTRY_TOKEN }}" >> .npmrc
      - name: Install Dependencies
        run: npm ci
      - name: Sync Capacitor
        run: npx cap sync
      - name: Build web assets
        run: npm run build
```

This workflow will authenticate with the Capawesome npm registry and install any private packages specified in your `package.json` file.

# GitLab CI/CD

You can use private Capawesome npm packages within your [GitLab CI/CD](https://docs.gitlab.com/ci/) pipelines by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a GitLab CI/CD Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your GitLab project as a CI/CD variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [CI/CD variables](https://docs.gitlab.com/ci/variables/). Make sure to mark the variable as masked and protected.

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Pipeline Configuration

### Configure the npm registry

Add the following script to your GitLab CI/CD pipeline **before** installing npm dependencies:

```
before_script:
  - echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
  - echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during GitLab CI/CD builds.

### Example

Here's a complete example of a GitLab CI/CD pipeline that builds an Ionic app using private Capawesome packages:

```
stages:
  - build

build-app:
  stage: build
  image: node:20
  before_script:
    - echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
    - echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
    - npm ci
  script:
    - npx cap sync
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
```

This pipeline will authenticate with the Capawesome npm registry and install any private packages specified in your `package.json` file.

# Ionic Appflow

You can use private Capawesome npm packages within your [Ionic Appflow](https://ionic.io/appflow) builds by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

Ionic Appflow is being discontinued

Ionic Appflow reaches end of life on December 31, 2027. [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Appflow. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details and [Migrating from Ionic Appflow](https://capawesome.io/docs/cloud/migrations/ionic-appflow/index.md) for the step-by-step guide.

## Preparation

### Create an Ionic Appflow Environment Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Ionic Appflow environment as an encrypted secret with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Using private npm modules](https://ionic.io/docs/appflow/cookbook/private_npm_modules).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Configuration

### Configure the npm registry

Create a new file named `.npmrc` in the root of your project and add the following content:

```
@capawesome-team:registry=https://npm.registry.capawesome.io
//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}
```

This file will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Ionic Appflow builds.

# Jenkins

You can use private Capawesome npm packages within your [Jenkins](https://www.jenkins.io/) pipelines by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create Jenkins Credentials

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Jenkins instance as a secret text credential with the ID `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Pipeline Configuration

### Configure the npm registry

Add the following script to your Jenkins pipeline **before** installing npm dependencies:

```
withCredentials([string(credentialsId: 'CAPAWESOME_NPM_REGISTRY_TOKEN', variable: 'CAPAWESOME_NPM_REGISTRY_TOKEN')]) {
    sh '''
        echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
        echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
    '''
}
```

This will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Jenkins builds.

### Example

Here's a complete example of a Jenkins pipeline that builds an Ionic app using private Capawesome packages:

```
pipeline {
    agent any

    environment {
        NODE_VERSION = '20'
    }

    stages {
        stage('Setup') {
            steps {
                // Install Node.js
                sh '''
                    curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | sudo -E bash -
                    sudo apt-get install -y nodejs
                '''
            }
        }

        stage('Configure Registry') {
            steps {
                withCredentials([string(credentialsId: 'CAPAWESOME_NPM_REGISTRY_TOKEN', variable: 'CAPAWESOME_NPM_REGISTRY_TOKEN')]) {
                    sh '''
                        echo "@capawesome-team:registry=https://npm.registry.capawesome.io" >> .npmrc
                        echo "//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}" >> .npmrc
                    '''
                }
            }
        }

        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Build') {
            steps {
                sh '''
                    npx cap sync
                    npm run build
                '''
            }
        }
    }

    post {
        always {
            // Clean up .npmrc file
            sh 'rm -f .npmrc'
        }
    }
}
```

# Vercel

You can use private Capawesome npm packages within your [Vercel](https://vercel.com/) deployments by configuring the Capawesome npm registry. This guide shows you how to set up authentication to access the private packages from the Capawesome Insiders program.

## Preparation

### Create a Vercel Environment Variable

[Get your license key](https://capawesome.io/docs/insiders/faq/#where-can-i-find-my-license-key) and add it to your Vercel project as an environment variable with the name `CAPAWESOME_NPM_REGISTRY_TOKEN` as described in [Environment variables](https://vercel.com/docs/projects/environment-variables).

Keep your license key secure

Never commit your license key directly to your repository and always use environment variables to store sensitive information like authentication tokens.

## Configuration

### Configure the npm registry

Create a `.npmrc` file in the root of your project with the following content:

```
@capawesome-team:registry=https://npm.registry.capawesome.io
//npm.registry.capawesome.io/:_authToken=${CAPAWESOME_NPM_REGISTRY_TOKEN}
```

This file will automatically configure npm to use the Capawesome registry for `@capawesome-team` packages during Vercel builds.
# Blog

# Blog

# Convert a Web App to a Mobile App in 11 Steps (2026)

You have a web app. Maybe you built it yourself, maybe you vibe-coded it with an AI assistant over a weekend. It works, you like it, and now you want to convert that web app to a mobile app on the App Store and Google Play.

The problem is that every tutorial you find was written for people who already live in Xcode and Android Studio. They assume you have a Mac, know what a provisioning profile is, and have configured Gradle before. If you're coming from the web world, or you're an [indie maker or early-stage startup](https://capawesome.io/solutions/startups/) who just shipped a React or Vue app, those guides feel like they start three levels above where you are.

This guide starts at zero. It covers every step from "I have a web app" to "my app is live on both stores and I can push fixes without waiting for review", using tools that handle the painful parts for you.

We've walked hundreds of users through this exact process. Here's everything we've learned, in one place.

**Key takeaways:**

- Converting a web app to a mobile app takes 11 steps: wrap it with Capacitor, add native features, then handle accounts, signing, builds, testing, and the store submission itself.
- Apple Developer Program enrollment costs $99/year and takes up to 48 hours to approve (5–7 business days if you need a D-U-N-S number for an organization account). Google Play Console is a $25 one-time fee.
- Capawesome Cloud builds both platforms on Apple Silicon M4 Pro hardware in 2–5 minutes, so no Mac is required for iOS.
- Google Play requires personal developer accounts created after November 13, 2023 to run a closed test with 12+ opted-in testers for 14 consecutive days before production access.
- Live Updates ship web-layer changes (HTML, CSS, JavaScript) directly to installed apps in minutes, skipping the 3–7 day store review that native changes still need.

## Who This Guide Is For

This guide is for you if any of these apply:

- You built a web app with React, Next.js, Vue, Angular, Svelte, or any other framework and want to ship it as a native app
- You're vibe-coding a product with Claude, Cursor, or Copilot and want to reach mobile users
- You have a working app but have no idea how to get it into the App Store
- You've been burned by App Store and Google Play Store review delays and want a way to push fixes instantly
- You need to build for iOS but don't own a Mac

By the end of this guide you'll have:

- A native iOS and Android app built from your existing web code
- Both apps live on the App Store and Google Play
- A system to push bug fixes and new features to users in minutes, without app store review

## The Full Picture: What You'll Use

Here's a map of the tools involved. Most of them are free or already covered by a single Capawesome Cloud subscription.

| What you need                                  | Tool                                                                                  | Cost              |
| ---------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------- |
| Convert web app to native                      | [Capacitor](https://capacitorjs.com/)                                                 | Free, open source |
| Add native features (camera, biometrics, etc.) | [Capawesome Plugins](https://capawesome.io/docs/sdks/capacitor/)                      | Free & paid       |
| AI-assisted setup                              | [Capawesome Skills](https://capawesome.io/skills/)                                    | Free              |
| Generate iOS certificates                      | [iOS Certificate Generator](https://capawesome.io/tools/ios-certificate-generator/)   | Free              |
| Generate Android keystore                      | [Android Keystore Generator](https://capawesome.io/tools/android-keystore-generator/) | Free              |
| Build iOS + Android in the cloud               | [Native Builds](https://capawesome.io/cloud/native-builds/)                           | Capawesome Cloud  |
| Publish to App Store + Google Play             | [App Store Publishing](https://capawesome.io/cloud/app-store-publishing/)             | Capawesome Cloud  |
| Push instant updates without review            | [Live Updates](https://capawesome.io/cloud/live-updates/)                             | Capawesome Cloud  |
| Automate the whole pipeline                    | [Automations](https://capawesome.io/cloud/automations/)                               | Capawesome Cloud  |
| Apple developer account                        | [developer.apple.com](https://developer.apple.com/programs/enroll/)                   | $99/year          |
| Google Play account                            | [play.google.com/console](https://play.google.com/console/signup)                     | $25 one-time      |

Let's walk through each step.

## Step 1: Convert Your Web App to Native with Capacitor

Converting a web app to a mobile app with [Capacitor](https://capacitorjs.com/) means keeping every line of your existing code. Capacitor packages your production build into an `ios/` and an `android/` project, hands it to the platform's native shell, and exposes device APIs to your JavaScript through plugins when you need them.

This is fundamentally different from React Native or Flutter: there's no rewrite and no new framework to learn. If you can `npm run build` your app today, you can have a native version of it running on a phone by the end of this afternoon.

### PWA vs. native app

Progressive Web Apps are great for some use cases, but they have hard limits when your goal is the app stores. Apple reviews submissions against [App Review Guideline 4.2, Minimum Functionality](https://developer.apple.com/app-store/review/guidelines/#minimum-functionality) and rejects apps that feel like a website with nothing app-like added, so a bare wrapper around your PWA is a common first-submission rejection. Google Play allows PWAs through [Trusted Web Activities](https://developer.chrome.com/docs/android/trusted-web-activity), but that route still leaves you with web-only capabilities on a store listing. Wrapping the same code with Capacitor and adding native features like push notifications or biometrics is what turns it into a submission both stores accept.

The day-to-day iOS limitations are just as real: Safari never shows an install prompt (users have to discover "Add to Home Screen" in the share menu on their own), web push only works on iOS 16.4 or later and only after the user has installed the app to their home screen, and device APIs like NFC, Bluetooth, and biometric-protected storage aren't available to web code at all.

A Capacitor app is a real, store-listed native app powered by the same web code. And it's not either/or: the same codebase can keep serving your PWA on the web while Capacitor ships it to both stores with full native API access.

### Production track record

Capacitor runs production apps used by millions of people every day, from indie makers to [Fortune 500 companies](https://ionic.io/customers) across fintech, healthcare, logistics, and consumer products. The framework is maintained by the Ionic team, has over 12,000 GitHub stars, and ships regular releases, so an entire ecosystem of tools, services, and companies depends on it long-term.

### Setting Up Capacitor

Install Capacitor in your existing web project:

```
npm install @capacitor/core @capacitor/cli
npx cap init
```

Add the iOS and Android platforms:

```
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android
```

Build your web assets and sync them to the native projects:

```
npm run build
npx cap sync
```

You now have a `ios/` and `android/` folder at the root of your project containing full native Xcode and Android Studio projects that point at your web build output. Every time you run `npx cap sync`, Capacitor compiles your web assets and copies them into the native projects, so the app always reflects your latest code.

### Works with any framework

Capacitor is framework-agnostic: the only thing that changes per framework is the `webDir` value, pointed at wherever your build command writes its output (`dist/` for a Vite-based React or Vue app, `www/` for Angular, `out/` for a Next.js static export).

This guide keeps moving through the pipeline from here. For the framework-specific config tables, the live reload dev workflow, WebView performance tips, and fixes for the most common setup errors (blank screen on launch, a plugin working on only one platform), see [Capacitor Setup Guide for Any Web Framework](https://capawesome.io/blog/build-mobile-apps-with-any-web-framework-and-capacitor/index.md). If your web app came out of Lovable specifically, [Convert Your Lovable App to iOS & Android Apps](https://capawesome.io/blog/convert-lovable-app-to-mobile-app/index.md) walks the same 11 steps with Lovable's export flow built in.

### The Vibe Coding Path: Let an AI Agent Do the Setup

If you're building with an AI coding assistant, install the [Capawesome Skills](https://capawesome.io/skills/) to give your agent deep Capacitor knowledge:

```
npx skills add capawesome-team/skills --skill capacitor-app-creation
```

Then prompt your agent (Claude Code, Cursor, Copilot):

```
Use the `capacitor-app-creation` skill to set up Capacitor in my project.
```

The agent will initialize Capacitor, add the platforms, fix your `capacitor.config.ts`, and sync everything, correctly on the first try, without you having to know what `npx cap sync` does.

## Step 2: Add Native Features with Plugins

A plain Capacitor app renders your web UI on a phone. Plugins connect your JavaScript code to native device features.

Here's a sample of what's possible with the [Capawesome plugin library](https://capawesome.io/docs/sdks/capacitor/):

### Authentication & Security

**[Biometrics Plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/)**: add Face ID, Touch ID, and fingerprint authentication to your app. One call to `authenticate()` handles the platform-specific prompt on both iOS and Android.

**[Vault Plugin](https://capawesome.io/docs/sdks/capacitor/vault/)**: store secrets (tokens, keys, passwords) behind biometric or device-passcode protection. Backed by hardware-level encryption on both platforms.

**[Apple Sign-In](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/) / [Google Sign-In](https://capawesome.io/docs/sdks/capacitor/google-sign-in/)**: native OAuth flows that look right on every device.

### Camera & Media

**[Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) / [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/)**: record and play back audio with full platform integration. Background playback, lock screen controls, the works.

**[File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/)**: let users pick files from their device with the native file browser. Returns the file URI or base64 data.

### Scanning & Recognition

**[ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/)**: on-device barcode and QR code scanning using Google's ML Kit. No server required.

**[ML Kit Document Scanner](https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner/)**: let users scan documents with edge detection and automatic cropping, just like a proper scanner app.

**[NFC Plugin](https://capawesome.io/docs/sdks/capacitor/nfc/)**: read and write NFC tags on both Android and iOS.

### Connectivity

**[Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/)**: connect to BLE peripherals such as fitness trackers, IoT devices, medical devices, and beacons.

**[WiFi Plugin](https://capawesome.io/docs/sdks/capacitor/wifi/)**: get WiFi state, SSID, and signal strength.

### Payments & Monetization

**[Purchases Plugin](https://capawesome.io/docs/sdks/capacitor/purchases/)**: in-app purchases and subscriptions via RevenueCat. One SDK, both stores.

**[Superwall Plugin](https://capawesome.io/docs/sdks/capacitor/superwall/)**: A/B test paywalls without app updates.

### Firebase Integration

The full [Firebase plugin suite](https://capawesome.io/docs/sdks/capacitor/firebase/) covers Analytics, Authentication, Crashlytics, Cloud Messaging (push notifications), Remote Config, Firestore, Cloud Storage, and more, each as a separate, tree-shakeable package.

### And Many More

Capawesome maintains [50+ plugins](https://capawesome.io/docs/sdks/capacitor/) covering sensors (accelerometer, barometer, pedometer), productivity (contacts, app shortcuts, badge count), printing, screen orientation, speech recognition and synthesis, SQLite, geolocation, and more.

Can't find the plugin you need?

Capawesome offers custom plugin development. The team has built custom Capacitor plugins for dozens of companies. [Get in touch.](https://capawesome.io/consulting/)

## Step 3: Create Your Developer Accounts

You need accounts on both platforms before anything can go live. This is a one-time setup, but it has real timelines you need to plan around.

### Apple Developer Program: $99/year

Sign up at [developer.apple.com/programs/enroll](https://developer.apple.com/programs/enroll/). Apple takes up to 48 hours to approve new accounts. If you're registering as an organization (to publish under a company name rather than your personal name), you'll also need a D-U-N-S number, which takes 5–7 business days to obtain.

Start this process first. It's the most common cause of delayed launches.

### Google Play Console: $25 one-time

Sign up at [play.google.com/console/signup](https://play.google.com/console/signup). The $25 fee is paid once and your account never expires. Identity verification usually completes within a few hours.

Full walkthrough: [How to Create Your Apple Developer and Google Play Developer Accounts](https://capawesome.io/blog/how-to-create-apple-developer-and-google-play-accounts/index.md)

## Step 4: Generate Your Signing Certificates

Every app submitted to the stores must be cryptographically signed. This is how Apple and Google verify the build came from you. You need:

- **iOS:** a distribution certificate + provisioning profile
- **Android:** a keystore file

This is where most first-timers get stuck. The official Apple documentation for code signing is notoriously opaque. You can generate everything you need directly in your browser, without Xcode or Android Studio.

### Free Browser Tools

**[iOS Certificate Generator](https://capawesome.io/tools/ios-certificate-generator/)** generates iOS development and distribution certificates along with a CSR file, the same thing you'd normally do through Keychain Access on a Mac, but in your browser. No sign-up, nothing leaves your device.

**[Android Keystore Generator](https://capawesome.io/tools/android-keystore-generator/)** creates a PKCS#12 keystore file for signing your Android app. Fill in the fields, download the file, store it somewhere safe. You'll need it for every future release.

**[iOS UDID Finder](https://capawesome.io/tools/ios-udid-finder/)**: if you need to register a test device for development builds, this finds your device UDID from any browser.

Once you have your certificates, upload them to Capawesome Cloud once. Every subsequent build picks them up automatically, with no local keychain required and no credentials in your CI environment variables.

- [Docs: iOS signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/ios/)
- [Docs: Android signing certificates](https://capawesome.io/docs/cloud/native-builds/certificates/android/)

For a detailed explanation of what certificates and provisioning profiles actually are:

[iOS Certificates and Provisioning Profiles Explained](https://capawesome.io/blog/ios-certificates-and-provisioning-profiles-explained/index.md)

## Step 5: Build Your Native App in the Cloud

Traditionally, building an iOS app requires a Mac with the right version of Xcode. Building a production Android APK requires Android Studio with the right Java and Gradle versions configured. Both need your signing credentials stored locally.

Capawesome Cloud [Native Builds](https://capawesome.io/cloud/native-builds/) eliminates all of that. You connect your Git repository, and the build happens on Apple Silicon M4 Pro hardware in the cloud. Typical build times are 2–5 minutes. You can trigger builds from Windows, Linux, or a Chromebook. No Mac required.

### How It Works

**Step 1: Connect your repository**

Link your GitHub, GitLab, Bitbucket, or Azure DevOps repository to Capawesome Cloud. This is a one-time OAuth authorization.

**Step 2: Trigger a build**

From the Capawesome Cloud Console, choose your branch, select iOS or Android, pick your build type (Debug, Release, Simulator), and hit Build.

**Step 3: Download or deploy**

When the build completes, download the IPA or APK/ABB directly, or chain it into an App Store Publishing destination with one click.

### Video Walkthroughs

Android build (full workflow from Git to downloadable ABB):

iOS build (Simulator build and signed Development build):

### Build From the CLI

You can also trigger builds from the terminal with the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/):

```
npx @capawesome/cli apps:builds:create \
  --platform ios \
  --buildType release
```

This makes it easy to plug Capawesome Cloud into any existing CI pipeline: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, or anything else.

### Advanced Features

- **[Environments](https://capawesome.io/docs/cloud/native-builds/environments/)**: define separate configurations for dev, staging, and production builds
- **[Auto-increment build numbers](https://capawesome.io/docs/cloud/native-builds/auto-incrementing-build-numbers/)**: never manually bump your build number again
- **[Build without Git](https://capawesome.io/docs/cloud/native-builds/build-without-git/)**: upload a ZIP if you don't want to connect a repository
- **[Assist — Ask AI](https://capawesome.io/docs/cloud/assist/)**: when a build fails, click Ask AI to get a plain-English diagnosis with a suggested fix

Full setup guide: [Getting Started with Native Builds](https://capawesome.io/docs/cloud/native-builds/setup/)

## Step 6: Distribute to Testers

Before going to the public stores, get your app onto real devices. Finding bugs on a physical device, especially iOS, is consistently different from finding them in a simulator.

Capawesome Cloud App Store Publishing supports all the major testing channels:

**TestFlight (iOS)**: upload your IPA to TestFlight and invite testers by email. Testers install the app from the TestFlight app. Internal testers (up to 100) skip the review queue; external testers go through a simplified review that usually takes a few hours.

**Google Play Internal Testing**: share your app via a link immediately after upload, with no review. Testers install it directly from the Play Store.

You can also install a build directly on a device from the Capawesome Cloud Console without going through any store:

Full guide: [How to Distribute iOS and Android Apps to Testers](https://capawesome.io/blog/how-to-distribute-ios-and-android-apps-to-testers/index.md)

## Step 7: Prepare Your Store Listing

This is where most first-timers hit an unexpected wall. The app is built, it works, but you can't submit it without a complete store listing. Apple and Google require:

- **App icon**: 1024×1024px for iOS (no transparency), 512×512px for Google Play
- **Screenshots**: Apple now requires iPhone 6.9" (1320×2868px) screenshots; these are mandatory
- **App name and description**: Apple gives you 30 characters for the name, 30 for a subtitle, and 100 characters of keywords (comma-separated, don't repeat what's in the name)
- **Privacy policy URL**: required by both platforms, even for free apps with no data collection
- **Age rating**: calculated from a questionnaire in each store's console
- **Data collection disclosures**: Apple's Privacy Nutrition Labels and Google's Data Safety section both require you to declare every type of data your app collects, including data from third-party SDKs

The full checklist with every requirement, device size, and tool recommendation:

[How to Prepare Your App Store Listing](https://capawesome.io/blog/how-to-prepare-your-app-store-listing/index.md)

## Step 8: Complete Google Play's Closed Testing Period

This is the most common surprise for first-time publishers, and it can delay your Android launch by weeks.

For personal developer accounts created after November 13, 2023, Google Play requires new apps to complete a closed testing period before they can publish to the public ([source](https://support.google.com/googleplay/android-developer/answer/14151465)):

- You need at least 12 testers who actively opt in via a special link
- The testing period must run for at least 14 consecutive days
- After 14 days with 12+ active testers, you can apply for production access

Organization accounts are not subject to this requirement.

This means your Google Play launch is a minimum of two weeks from when you have 12 testers opted in. Start recruiting testers the moment your first Android build is ready. Don't wait until you're "ready to launch."

Good places to find testers: your existing user base (if any), the [Capawesome Discord community](https://discord.gg/VCXxSVjefW), your company's Slack, friends, family.

The App Store does not have this requirement. iOS apps go live immediately after Apple's review.

## Step 9: Submit for Review

With your store listing complete and testing done, you're ready to submit.

### App Store (iOS)

In App Store Connect, set your app's release strategy (manual or automatic after approval), assign the build you want to submit, and click Submit for Review. Apple's review typically takes 3–5 days for new apps.

Common reasons for rejection:

- Missing privacy policy
- App crashes on launch (test on a real device, not just a simulator)
- Metadata mismatch (screenshots don't match the app's actual UI)
- Missing required functionality explanations
- Login credentials not provided. You must provide the review team with an active and functional test account. Because App Review is an automated and manual process, the reviewers cannot access account-restricted features without valid login information.

Be careful with all these requirements, because even though you can resubmit your app after a rejection, each resubmission takes longer to be reviewed.

### Google Play

After your closed testing period, apply for production access in the Google Play Console. Once approved, your initial review typically takes 3–7 days.

### Automated Submissions with Capawesome Cloud

Capawesome Cloud [App Store Publishing](https://capawesome.io/cloud/app-store-publishing/) automates the submission step entirely. You connect your App Store Connect API key and Google Play service account once, configure your store destinations, and then publish with a single click, or automatically on every successful native build via [Automations](https://capawesome.io/docs/cloud/automations/setup/).

Supported destinations:

- Apple App Store (production)
- TestFlight (internal and external)
- Google Play (Internal, Alpha, Beta, Production)
- Firebase App Distribution

When a submission fails, [Ask AI](https://capawesome.io/docs/cloud/assist/) in the Capawesome Console parses Apple's or Google's validator output and tells you exactly what went wrong and how to fix it, in plain language.

## Step 10: Set Up Live Updates (Your Biggest Advantage)

Once your app is approved, every change you ship (a bug fix, a copy tweak, a new feature) must go through the App Store review queue. That's 1–5 days.

Live Updates bypass the queue entirely.

Because Capacitor separates your app into a native shell and a web layer (HTML, CSS, JavaScript, and static assets), you can update the web layer over the air, directly to users' devices, in minutes. Here's what developers like you said after shipping their first app with Capawesome:

**King Arthur Baking:** *"We can quickly deliver improvements without app store delays, saving time and resources while keeping the experience fresh for our baking community."*

**snapAddy**: *"We now deliver daily live updates to more than 200,000 devices without any issues."*

**Summon Worlds**: *"We mainly use over-the-air (OTA) updates to deliver critical bug fixes and updates when waiting on the App Store review process is not an option."*

### What Live Updates Can and Can't Do

**Can update:** any change to your HTML, CSS, JavaScript, images, fonts, JSON data, and other static assets.

**Cannot update:** changes that require new native code, new Capacitor plugins, new iOS/Android permissions, or changes to `Info.plist` / `AndroidManifest.xml`. Those still need a native build and a store review.

In practice, the vast majority of day-to-day iteration (UI changes, bug fixes, new screens, content updates) falls in the "can update" category.

### Setup

Install the Live Update plugin:

```
npm install @capawesome/capacitor-live-update@latest
npx cap sync
```

Configure it in `capacitor.config.ts`:

```
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: 'your-app-id-from-capawesome-cloud',
      autoUpdateStrategy: 'background',
    },
  },
};

export default config;
```

`autoUpdateStrategy: 'background'` is the recommended default. The app checks for updates at every launch, downloads them silently in the background, and applies them the next time the user opens the app. No code changes, no user prompts.

Shipping a fix from that point forward:

```
npm run build
npx @capawesome/cli apps:liveupdates:upload
```

Every user gets the fix on their next app launch.

### Advanced Live Update Features

Capawesome Cloud Live Updates includes features that enterprise teams depend on:

**[Channels](https://capawesome.io/docs/cloud/live-updates/channels/)**: ship different bundles to different user segments. Useful for A/B testing, staged rollouts, or keeping your beta users on a separate track.

**[Rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/)**: gradually roll out a new bundle to 10%, 25%, 50%, then 100% of users. Watch your error rates before committing to a full release.

**[Rollbacks](https://capawesome.io/docs/cloud/live-updates/rollbacks/)**: if something goes wrong, roll back to the previous bundle instantly from the console.

**[Code Signing](https://capawesome.io/docs/cloud/live-updates/code-signing/)**: RSA-sign your bundles so the Live Update SDK verifies authenticity on every device before applying an update.

**[Delta Updates](https://capawesome.io/docs/cloud/live-updates/bundle-size/)**: only ship the files that changed, not the entire bundle. Reduces update size and delivery time for returning users.

**[Device Management](https://capawesome.io/docs/cloud/live-updates/devices/)**: force specific devices to a specific channel. Great for QA devices, internal testing, or enterprise deployments.

Note

Include the Live Update plugin in your first release, even before you have updates to ship. Adding a new plugin requires a new Native Build and another store review, and that's exactly the situation you don't want to be in when you're trying to push a critical fix.

**Full documentation:**

- [Getting Started with Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/)
- [Capacitor Live Updates: A Complete Guide to OTA Updates](https://capawesome.io/blog/capacitor-live-updates-guide/index.md)
- [Update Strategies](https://capawesome.io/docs/cloud/live-updates/update-strategies/)
- [Live Updates Best Practices](https://capawesome.io/docs/cloud/live-updates/)

## Step 11: Automate Everything

Once you're comfortable with the flow, the final step is connecting the pieces so that a `git push` triggers the entire pipeline without you touching a dashboard.

[Capawesome Cloud Automations](https://capawesome.io/docs/cloud/automations/setup/) lets you define end-to-end pipelines:

```
git push to main
  → Trigger Native Build (iOS + Android)
  → On success: publish to TestFlight + Google Play Internal
  → On build approval: deploy Live Update to production channel
```

Automations can be triggered on a Git push to a specific branch or tag. When a build or deployment completes, Capawesome Cloud can send a [webhook](https://capawesome.io/docs/cloud/automations/webhooks/) with the result. You can post notifications to Slack, Microsoft Teams, Discord, or any other tool, so your team knows when a build succeeds or fails without watching the console.

For CI/CD pipelines you already have, the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/) and [REST API](https://capawesome.io/docs/cloud/api/) let you trigger any action from GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps, or Jenkins.

**Guides:**

- [Capacitor CI/CD in 2026: Why Specialization Wins](https://capawesome.io/blog/ci-cd-for-capacitor-apps/index.md)
- [CI/CD for Capacitor: Common Pitfalls and How to Avoid Them](https://capawesome.io/blog/ci-cd-for-capacitor-common-pitfalls/index.md)
- [GitHub Actions integration](https://capawesome.io/docs/cloud/live-updates/integrations/github-actions/)
- [GitLab CI/CD integration](https://capawesome.io/docs/cloud/live-updates/integrations/gitlab-ci/)

## Everything Inside Capawesome Cloud

Here's the full picture of what Capawesome Cloud gives you: one subscription, one dashboard. All plans include a 14-day free trial.

### Native Builds

Cloud-based iOS and Android builds on Apple Silicon M4 Pro. No Mac, no build servers to manage. Average build time: 2–5 minutes. Includes managed code signing, build history, downloadable artifacts, environment variables, and full build logs.

Thousands of native builds are completed on Capawesome Cloud every month.

### Live Updates

OTA updates delivered over a global CDN. Includes channels, rollouts, rollbacks, RSA code signing, delta updates, device management, and analytics.

### App Store Publishing

One-click submissions to TestFlight, the App Store, Google Play (all tracks), and Firebase App Distribution. Supports multiple destinations per app, ideal for [white-label](https://capawesome.io/solutions/white-label/) products or regional variants. Encrypted credentials, protected destinations with role-based access control, and full audit logs.

Thousands of App Store updates are deployed every month.

### Automations

Automatically trigger native builds from Git events, on every push to a branch or on tag creation. Chain builds with store publishing and live update deployments in a single pipeline. When a build completes, Capawesome Cloud sends a [webhook](https://capawesome.io/docs/cloud/automations/webhooks/) with the result so you can connect it to any notification tool.

### Assist: AI Diagnostics

When a build or deployment fails, Ask AI turns the raw validator output from Apple, Google, or your build logs into a plain-language cause → explanation → suggested fix. Opt-in per click, zero data retention.

### Integrations

GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, Git (HTTP/S), Slack, Microsoft Teams, Discord.

### Security & Compliance

- GDPR compliant, data hosted in Germany
- ISO 27001 certified (our data center partners)
- SOC 2 Type II (report available on request)
- All credentials encrypted at rest
- RSA code signing for live update bundles

## Expert help available

Building a Capacitor app is learnable, but sometimes you need someone who's already made all the mistakes. The Capawesome team offers [consulting services](https://capawesome.io/consulting/) for teams that need hands-on help:

- **Capacitor app development**: architecture, development, deployment, and maintenance
- **Custom Capacitor plugins**: if no existing plugin does what you need, we build it. We've delivered custom plugins for dozens of companies, often within a few days
- **Collaborative support**: work alongside your team for architecture reviews, code reviews, debugging, and pairing sessions
- **CI/CD setup**: get your build and deployment pipeline configured correctly from the start

Some reviews from our users:

*"We had to use an Android and iOS SDK in our Capacitor app, for which no plugin existed. Capawesome was able to create a fully functional Capacitor plugin for us within a few days. The communication was excellent and the plugin works perfectly."* (Daniel Ehrhardt, CEO at Codext GmbH)

*"Our Capacitor app had several unique requirements for running operations in the background. The Capawesome team was able to quickly understand our needs and crafted a customized Capacitor plugin that exceeded our expectations."* (Christofer Huber, CTO at WEBPUNKS GmbH)

[Talk to us about your project →](https://capawesome.io/consulting/) if you'd rather have hands-on help than DIY the whole pipeline.

## Pre-launch checklist

Use this before you submit:

**Foundation**

- Web app builds successfully (`npm run build`)
- Capacitor initialized and platforms added (`npx cap add ios`, `npx cap add android`)
- Native features added via plugins as needed
- Live Update plugin installed and configured
- App tested on a real device (not just browser/simulator)

**Accounts**

- Apple Developer Program account created and approved ($99/yr)
- Google Play Console account created ($25 one-time)

**Certificates**

- iOS distribution certificate generated and uploaded to Capawesome Cloud
- iOS provisioning profile generated and uploaded
- Android keystore generated and uploaded to Capawesome Cloud

**Build & Test**

- First native build completed via Capawesome Cloud (Debug or Simulator)
- App distributed to testers via TestFlight / Google Play Internal / Firebase App Distribution
- Bugs found on real devices fixed

**Store Listing**

- App icon ready (1024×1024 for iOS, 512×512 for Android)
- iPhone screenshots ready (required by Apple)
- iPad screenshots ready (if app supports iPad)
- Google Play screenshots ready (minimum 2)
- App name, subtitle/short description, full description written
- Keywords ready (iOS: 100 chars; Google Play: embedded in description)
- Privacy policy URL live and accessible
- Age rating completed in App Store Connect and Google Play Console
- Apple Privacy Nutrition Labels completed
- Google Data Safety section completed

**Google Play Only**

- Closed testing track created with 12+ testers opted in
- 14-day testing period completed
- Production access applied for

**Submission**

- Release build created via Capawesome Cloud (signed, production)
- App submitted for review on App Store
- App submitted for review on Google Play

**Post-Launch**

- First live update bundle deployed
- Automations configured for future releases

## FAQ

### How do I convert a web app to a mobile app?

Wrap it with [Capacitor](https://capacitorjs.com/): `npm install @capacitor/core @capacitor/cli`, `npx cap init`, then `npx cap add ios` and `npx cap add android`. Your existing web code (React, Vue, Angular, Svelte, or plain HTML) runs unchanged inside a native shell — no rewrite, no new framework. From there, the remaining work is signing certificates, a native build, and the store submissions, which is what Steps 3 through 9 of this guide cover.

### Do I need a Mac to publish my web app to the App Store?

No. Signing certificates can be generated in the browser with the free [iOS Certificate Generator](https://capawesome.io/tools/ios-certificate-generator/), and the actual iOS build runs on Capawesome Cloud's own Apple Silicon M4 Pro hardware. You can trigger it from Windows, Linux, or a Chromebook.

### What's the single biggest reason indie launches get delayed?

Google Play's closed testing requirement, by far. If your personal developer account was created after November 13, 2023, Google requires at least 12 opted-in testers running your app for 14 consecutive days before you can apply for production access. That's a hard two-week floor on your Android launch that has nothing to do with how polished your app is. Start [recruiting testers](https://capawesome.io/solutions/beta-testing/) the moment your first Android build exists, not when you feel "ready to launch."

### Realistically, how long does the whole process take from zero to live?

Budget at least 3-4 weeks if you're starting from scratch: up to 48 hours for Apple Developer Program approval (5-7 business days if you need a D-U-N-S number for an organization account), the 14-day Google Play closed testing period running in parallel, then 3-5 days for Apple's review and 3-7 days for Google's initial review. The Apple Developer account and Google Play testers are the two things worth starting on day one, since everything else can happen while you wait on those.

### Can Live Updates really let me skip app store review entirely?

Only for a specific category of changes. Live Updates ship anything in your web layer (HTML, CSS, JavaScript, images, fonts, JSON data) directly to installed apps, no review queue. They cannot ship new native code, new Capacitor plugins, new platform permissions, or changes to `Info.plist` / `AndroidManifest.xml`; those still need a native build and a store review. In practice, most day-to-day iteration (UI tweaks, bug fixes, new screens, content changes) falls into the "can update" bucket.

### What are the most common reasons an App Store submission gets rejected?

A missing privacy policy URL, the app crashing on a real device (testing only in a simulator hides plenty of bugs), screenshots that don't match the app's actual UI, and, very commonly, not providing reviewers with a working test account. Apple's review is partly manual, and reviewers can't access account-restricted features without valid login credentials, so a submission without one is an easy rejection to avoid.

### Do I need to add the Live Update plugin from day one, even before I have anything to update?

Yes. Adding a new Capacitor plugin later requires a new native build and another store review, precisely the delay you're trying to avoid when you eventually need to [push a critical fix](https://capawesome.io/solutions/hotfixes/). Shipping the Live Update plugin in your very first release means the update channel is already there when you need it.

## Try Capawesome Cloud

Every step in this guide after "install Capacitor" (signing, native builds, store submissions, Live Updates, automation) runs on one Capawesome Cloud subscription with a 14-day free trial.

[Start your 14-day free trial →](https://console.cloud.capawesome.io)

## Final Thoughts

Start with the two things you cannot speed up: enroll in the Apple Developer Program and recruit your 12 Google Play testers on day one. The certificates, the builds, and the store listing can all happen while those two clocks run.

Install the Live Update plugin before your first submission. Adding it later costs you another native build and another store review, at the moment you can least afford one.

Once your app is live, [Capacitor Setup Guide for Any Web Framework](https://capawesome.io/blog/build-mobile-apps-with-any-web-framework-and-capacitor/index.md) covers the day-to-day workflow: live reload, WebView performance, and fixes for the setup errors you'll hit as the app grows.

If you get stuck at any step, ask in the [Capawesome Discord](https://discord.gg/VCXxSVjefW), and subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) for updates on new plugins, Cloud features, and guides like this one.

# Capawesome December 2024 Update

The Capawesome December update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). There are also some news from the community. Let's take a look at the most important changes.

In case you missed it, check out the [November 2024 update](https://capawesome.io/blog/2024-november-update/index.md) to catch up on what shipped last month.

## CLI

### `login` command no longer creates tokens

Until now, the `login` command created a new token every time you logged in using email and password. However, tokens were originally only intended for the API and CI/CD. To avoid confusion, the `login` command no longer creates tokens. Instead, a session is created, which is automatically deleted after 30 days of inactivity.

## Cloud

### Unsubscribe from notifications

You can now unsubscribe from notifications via the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/notifications). Simply navigate to the `Notifications` page and select the notifications you want to subscribe to or unsubscribe from.

\[

\](/docs/assets/videos/posts/cloud-notifications-subscriptions.mp4)

### Manage sessions

You can now manage your sessions via the [Capawesome Cloud Console](https://console.cloud.capawesome.io/settings/sessions). Simply navigate to the `Sessions` page and view all your active sessions. You can also revoke sessions if needed.

\[

\](/docs/assets/videos/posts/20241231_cloud-sessions.mp4)

## Plugins

### Android Foreground Service

The [Capacitor Android Foreground Service plugin](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/index.md) now has a new `serviceType` option that allows you to specify the type of the foreground service:

```
import { ForegroundService, ServiceType } from '@capawesome-team/capacitor-android-foreground-service';

const startForegroundService = async () => {
  await ForegroundService.startForegroundService({
    id: 1,
    title: 'Recording',
    body: 'Recording audio in the background',
    smallIcon: 'ic_stat_icon_config_sample',
    serviceType: ServiceType.Microphone
  });
};
```

For now, only two service types are supported. Feel free to open an issue if you are missing a specific service type.

### App Shortcuts

We have published a new [Capacitor App Shortcuts plugin](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/index.md) that allows you to manage app shortcuts and quick actions on Android and iOS. The plugin can be installed via the public npm registry:

```
npm install @capawesome/capacitor-app-shortcuts
```

Here is an example of how to use the plugin:

```
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const set = async () => {
  await AppShortcuts.set({
    shortcuts: [
      {
        id: 'feedback',
        title: 'Feedback',
      }
    ],
  });
};
```

| Android | iOS |
| ------- | --- |
|         |     |

### Firebase Analytics

The [Capacitor Firebase Analytics plugin](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/index.md) now supports the Firebase JS SDK 11.

### Firebase App

The [Capacitor Firebase App plugin](https://capawesome.io/docs/sdks/capacitor/firebase/app/index.md) now supports the Firebase JS SDK 11.

### Firebase App Check

The [Capacitor Firebase App Check plugin](https://capawesome.io/docs/sdks/capacitor/firebase/app-check/index.md) now supports the Firebase JS SDK 11.

### Firebase Authentication

The [Capacitor Firebase Authentication plugin](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/index.md) received multiple updates this month.

##### Firebase JS SDK 11

The plugin now supports the Firebase JS SDK 11.

##### Facebook iOS SDK

The [Facebook iOS SDK](https://github.com/facebook/facebook-ios-sdk) was updated to version 17.1.0.

##### New `idTokenChange` listener

The plugin now has a new `idTokenChange` listener that allows you to listen for changes to the ID token:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const addListener = async () => {
  FirebaseAuthentication.addListener('idTokenChange', async (event) => {
    console.log(event);
  });
};
```

##### New `verifyBeforeUpdateEmail` method

The plugin now has a new `verifyBeforeUpdateEmail` method that allows you to verify the email before updating it:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const verifyBeforeUpdateEmail = async () => {
  await FirebaseAuthentication.verifyBeforeUpdateEmail({
    newEmail: 'mail@example.com',
    actionCodeSettings: {
      url: 'https://www.example.com/cart?email=user@example.com&cartId=123',
      iOS: {
        bundleId: 'com.example.ios'
      },
      android: {
        packageName: 'com.example.android',
        installApp: true,
        minimumVersion: '12'
      },
      handleCodeInApp: true
    }
  });
};
```

### Firebase Cloud Firestore

The [Capacitor Firebase Cloud Firestore plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) now supports the Firebase JS SDK 11.

### Firebase Cloud Functions

The [Capacitor Firebase Cloud Functions plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/index.md) received multiple updates this month.

##### Firebase JS SDK 11

The plugin now supports the Firebase JS SDK 11.

##### New `regionOrCustomDomain` option

The `UseEmulatorOptions` interface now has a new `regionOrCustomDomain` option that allows you to specify the region or custom domain for the emulator:

```
import { FirebaseFunctions } from '@capacitor-firebase/functions';

const useEmulator = async () => {
  await FirebaseFunctions.useEmulator({
    host: '10.0.2.2',
    port: 9001,
    regionOrCustomDomain: 'us-central1'
  });
};
```

### Firebase Cloud Messaging

The [Capacitor Firebase Cloud Messaging plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/index.md) now supports the Firebase JS SDK 11.

### Firebase Cloud Storage

The [Capacitor Firebase Cloud Storage plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/index.md) now supports the Firebase JS SDK 11.

### Firebase Performance Monitoring

The [Capacitor Firebase Performance Monitoring plugin](https://capawesome.io/docs/sdks/capacitor/firebase/performance-monitoring/index.md) received multiple updates this month.

##### Firebase JS SDK 11

The plugin now supports the Firebase JS SDK 11.

##### New methods

The plugin got a few new methods that allow you to put and get attributes and metrics for a trace:

```
import { FirebasePerformance } from '@capacitor-firebase/performance';

const putAttribute = async () => {
  await FirebasePerformance.putAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
    value: '123',
  });
};

const getAttribute = async () => {
  const result = await FirebasePerformance.getAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
  return result.attributes;
};

const getAttributes = async () => {
  const result = await FirebasePerformance.getAttributes({ traceName: 'test_trace' });
  return result.attributes;
};

const removeAttribute = async () => {
  await FirebasePerformance.removeAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
};

const putMetric = async () => {
  await FirebasePerformance.putMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
    num: 1,
  });
};

const getMetric = async () => {
  const result = await FirebasePerformance.getMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
  });
  return result.value;
};

const record = async () => {
  await FirebasePerformance.record({
    traceName: 'test_trace',
    startTime: Date.now(),
    duration: 1000,
    options: {
      metrics: {
        item_cache_hit: 1,
      },
      attributes: {
        user_id: '123',
      },
    },
  });
};
```

### Firebase Remote Config

The [Capacitor Firebase Remote Config plugin](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/index.md) now supports the Firebase JS SDK 11.

### Live Update

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) received multiple updates this month.

##### New `getCurrentBundle()` and `getNextBundle()` methods

The plugin now has new [`getCurrentBundle()`](https://capawesome.io/docs/sdks/capacitor/live-update/#getcurrentbundle) and [`getNextBundle()`](https://capawesome.io/docs/sdks/capacitor/live-update/#getnextbundle) methods that allow you to get the current and next bundle:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

/**
 * Get the bundle identifier of the current bundle. 
 * The current bundle is the bundle that is currently used by the app.
 */
const getCurrentBundle = async () => {
  const { bundleId } = await LiveUpdate.getCurrentBundle();
  return bundleId;
};

/**
 * Get the bundle identifier of the next bundle. 
 * The next bundle is the bundle that will be used after calling `reload()` or restarting the app.
 */
const getNextBundle = async () => {
  const { bundleId } = await LiveUpdate.getNextBundle();
  return bundleId;
};
```

This change deprecated the [`getBundle()`](https://capawesome.io/docs/sdks/capacitor/live-update/#getbundle) method.

##### New `setNextBundle(...)` method

The plugin now has a new [`setNextBundle(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#setnextbundle) method that allows you to set the next bundle:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

/**
 * Set the next bundle. 
 * The next bundle is the bundle that will be used after calling `reload()` or restarting the app.
 */
const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({
    bundleId: '4b678425-fe57-485d-a8ff-a08af915bd29',
  });
};
```

This change deprecated the [`setBundle(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#setbundle) method.

##### New `channel` property

The [`fetchLatestBundle(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#fetchlatestbundle) and [`sync(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#sync) methods now have a new `channel` property that allows you to specify the name of the channel where the latest bundle is fetched from:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

/**
 * Fetch the latest bundle from the specified channel.
 */
const fetchLatestBundle = async () => {
  const result = await LiveUpdate.fetchLatestBundle({
    channel: 'production-5',
  });
  return result;
};

/**
 * Sync the latest bundle from the specified channel.
 */
const sync = async () => {
  const result = await LiveUpdate.sync({
    channel: 'production-5',
  });
  return result;
};
```

##### New `FetchLatestBundleResult` properties

The [`fetchLatestBundle(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#fetchlatestbundle) method now returns a `artifactType` and `downloadUrl` property:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const fetchLatestBundle = async () => {
  const result = await LiveUpdate.fetchLatestBundle();
  return {
    artifactType: result.artifactType,
    bundleId: result.bundleId,
    downloadUrl: result.downloadUrl,
  };
};
```

### NFC

The [Capacitor NFC plugin](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) received multiple updates this month.

##### New `manufacturerCode` property

The plugin is now also able to read the IC Manufacturer Code for ISO15693 tags:

```
import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc';

const readManufacturerCode = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      // Stop the NFC scan session
      await Nfc.stopScanSession();
      // Return the IC Manufacturer Code
      resolve(event.nfcTag.manufacturerCode);
    });
    // Start the NFC scan session
    void Nfc.startScanSession();
  });
};
```

##### HCE support

The plugin now supports [Host Card Emulation (HCE)](https://developer.android.com/develop/connectivity/nfc/hce) on Android. This allows you to emulate an NFC tag on your device and respond to commands from an NFC reader. Here is an example of how to use this feature:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const addListener = async () => {
  Nfc.addListener('commandReceived', async (event) => {
    // Do something with the received command
    console.log(event.data);
    // Respond to the command
      await respond({ data: [...] });
  });
};
```

##### 0x24 command support

The plugin now supports the Write Multiple Blocks command (0x24 command code), as defined in the ISO 15693-3 specification, also on iOS:

```
import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc';

const writeMultipleBlocks = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      // Write multiple blocks to the NFC tag
      await Nfc.transceive({ 
        techType: NfcTagTechType.NfcV, 
        data: [...], 
        iso15693RequestFlags: [...], 
        iso15693CommandCode: 0x24 
      });
      // Stop the NFC scan session
      await Nfc.stopScanSession();
      resolve();
    });
    // Start the NFC scan session
    void Nfc.startScanSession();
  });
};
```

### Printer

The [Capacitor Printer plugin](https://capawesome.io/docs/sdks/capacitor/printer/index.md) now also supports the web, at least with the `printWebView` method:

```
import { Printer } from '@capawesome-team/capacitor-printer';

const print = async () => {
  await Printer.printWebView({
    content: '<h1>Hello, World!</h1>',
  });
};
```

You can also use a print style sheet to customize the print output:

```
@media print {
  h1 {
    color: red;
  }
}
```

For more information, check out the [mdn web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Printing).

### Speech Recognition

We have published a new [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) that allows you to transcribe speech to text. The plugin supports Android, iOS, and the web. It comes with a simple API that allows you to start and stop the recognition process:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const startListening = async () => {
  // Print the recognized text to the console
  await SpeechRecognition.addListener('result', (event) => {
    console.log('Result:', event.result);
  });
  // Start listening for speech
  await SpeechRecognition.startListening({
    language: 'en-US',
    silenceThreshold: 2000,
  });
};
```

Besides that, there are a few special features like the ability to set a silence threshold. The plugin is now available to all [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md).

### Speech Synthesis

We have also published a new [Capacitor Speech Synthesis plugin](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) that allows you to convert text to speech. The plugin supports Android, iOS, and the web. You can customize the voice, pitch, and rate of the speech. Here is an example of how to use the plugin:

```
import { SpeechSynthesis, QueueStrategy } from '@capawesome-team/capacitor-speech-synthesis';

const speak = async () => {
  // Print every spoken word to the console
  await SpeechSynthesis.addListener('boundary', (event) => {
    console.log('boundary', event);
  });
  // Speak the text
  await SpeechSynthesis.speak({
    language: 'en-US',
    pitch: 1.0,
    queueStrategy: QueueStrategy.Add,
    rate: 1.0,
    text: 'Hello, World!',
    voiceId: 'com.apple.ttsbundle.Samantha-compact',
    volume: 1.0,
  });
};
```

The plugin is now available to all [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md).

### Torch

The [Capacitor Torch plugin](https://capawesome.io/docs/sdks/capacitor/torch/index.md) now also supports the web using the [Media Capture and Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API):

```
import { Torch } from '@capawesome/capacitor-torch';

const enable = async () => {
  await Torch.enable();
};
```

### Wifi

The [Capacitor Wifi plugin](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) got a new configuration option that allows you to force the usage of the deprecated `WifiManager` API on Android as there have been several reports that the new `WifiNetworkSpecifier` API is not yet working as expected on some devices.

You can enable the `useWifiManager` option in the Capacitor configuration file:

```
{
  "plugins": {
    "Wifi": {
      "useWifiManager": true
    }
  }
}
```

## Community

### Build a mobile app with Qwik and Capacitor

[@srapport](https://github.com/srapport) published the official [Qwik for iOS and Android](https://qwik.dev/docs/guides/capacitor/) guide this month. The guide explains how to create a mobile app for Android and iOS with Qwik using Capacitor and highlights what you need to pay attention to. This also includes a short introduction to the Capacitor Live Update plugin from Capawesome. Check out the guide [here](https://qwik.dev/docs/guides/capacitor/).

# Capawesome November 2024 Update

The Capawesome November update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Cloud

### Automatically delete old bundles

There are now two new options available for automatically deleting old bundles so that you don't have to worry about the storage limit:

1. **Set a bundle limit**: You can set a limit for the number of bundles that can be assigned to a channel. If this limit is reached, the oldest bundle will be deleted automatically. For example, this is how you can set a bundle limit of 5 using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) when creating a channel:

   ```
   npx @capawesome/cli apps:channels:create --bundle-limit 5
   ```

1. **Set an expiration date**: You can set an expiration date for a bundle. If this date is reached, the bundle will be deleted automatically. For example, this is how you can automatically delete a bundle after 30 days using the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) when creating a bundle:

   ```
   npx @capawesome/cli apps:bundles:create --expires-in-days 30
   ```

Both options are also available via the [Capawesome Cloud Console](https://console.cloud.capawesome.io).

### Delete multiple items at once

You can now finally delete multiple Bundles, Channels, Devices and Tokens at once via the [Capawesome Cloud Console](https://console.cloud.capawesome.io). Simply select the items you want to delete and click the `Delete` button.

\[

\](/docs/assets/videos/posts/cloud-delete-multiple-items.mp4)

## Plugins

### Android Foreground Service

The [Capacitor Android Foreground Service plugin](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/index.md) now has three new methods that allow you to update the foreground service notification and create/delete notification channels:

```
import { ForegroundService, Importance } from '@capawesome-team/capacitor-android-foreground-service';

/**
 * Update the foreground service notification.
 */
const updateForegroundService = async () => {
  await ForegroundService.updateForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
  });
};

/**
 * Create a notification channel.
 */
const createNotificationChannel = async () => {
  await ForegroundService.createNotificationChannel({
    id: 'default',
    name: 'Default',
    description: 'Default channel',
    importance: Importance.Default,
  });
};

/**
 * Delete a notification channel.
 */
const deleteNotificationChannel = async () => {
  await ForegroundService.deleteNotificationChannel({
    id: 'default',
  });
};
```

Thanks to [@xsorifc28](https://github.com/xsorifc28) and [@ebarooni](https://github.com/ebarooni) for the contributions!

### App Review

Say hi to our brand new [Capacitor App Review plugin](https://capawesome.io/docs/sdks/capacitor/app-review/index.md) for Android and iOS! This plugin not only allows you to request in-app reviews but also to open the app store page of your app and, if possible, open the dialog to leave a review. Here is an example of how you can use this plugin:

```
import { AppReview } from '@capawesome/capacitor-app-review';

const openAppStore = async () => {
  await AppReview.openAppStore({
    appId: '123456789'
  });
};

const requestReview = async () => {
  await AppReview.requestReview();
};
```

Thanks to [@mertyldrr](https://github.com/mertyldrr) for the contribution!

### App Update

The [Capacitor App Update plugin](https://capawesome.io/docs/sdks/capacitor/app-update/index.md) now has a new `appId` property that allows you to specify the app ID of your app:

```
import { AppUpdate } from '@capawesome/capacitor-app-update';

const openAppStore = async () => {
  await AppUpdate.openAppStore({
    appId: '123456789'
  });
};
```

This solves the problem where the app was not always found in the App Store and speeds up the entire plugin call.

### File Picker

The [Capacitor File Picker plugin](https://capawesome.io/docs/sdks/capacitor/file-picker/index.md) now has a new `pickDirectory` method that allows you to pick a directory:

```
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickDirectory = async () => {
  const result = await FilePicker.pickDirectory();
  console.log('Picked directory path:', result.path);
};
```

In combination with the [Filesystem](https://capacitorjs.com/docs/apis/filesystem) plugin, you can now easily access multiple files in a directory at once without having to select each file individually.

Thanks to [@ebarooni](https://github.com/ebarooni) for the contribution!

### ML Kit Barcode Scanning

The [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin got two new features this month.

##### Compatibility with Torch Plugin

The plugin is now compatible with the [Capacitor Torch plugin](https://capawesome.io/docs/sdks/capacitor/torch/index.md) which means that you no longer have to use the deprecated torch methods of the ML Kit Barcode Scanning plugin.

##### Barcode Value Types

The plugin now returns the value types of the scanned barcodes. The following value types are available:

- [`BarcodeCalendarEvent`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodecalendarevent)
- [`BarcodeContactInfo`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodecontactinfo)
- [`BarcodeDriverLicense`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodedriverlicense)
- [`BarcodeEmail`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodeemail)
- [`BarcodeGeoPoint`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodegeopoint)
- [`BarcodePhone`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodephone)
- [`BarcodeSms`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodesms)
- [`BarcodeUrlBookmark`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodeurlbookmark)
- [`BarcodeWifi`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#barcodewifi)

Thanks to [@mertyldrr](https://github.com/mertyldrr) for the contribution!

### NFC

The [Capacitor NFC plugin](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) now has a new `compatibilityMode` flag that can help reading some special NDEF tags:

```
import { Nfc } from '@capawesome-team/capacitor-nfc';

const startScanSession = async () => {
  await Nfc.startScanSession({ 
    compatibilityMode: true 
  });
};
```

Please be aware that this mode only supports reading NDEF tags and is only available on iOS.

### Torch

The [Capacitor Torch plugin](https://capawesome.io/docs/sdks/capacitor/torch/index.md) has also been updated to be compatible with the [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin. This means that you can now use the Torch plugin to toggle the flashlight even when scanning barcodes.

### Wifi

The [Capacitor Wifi plugin](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) now returns the security types and signal strength for scanned networks:

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const scan = async () => {
  await Wifi.addListener('networksScanned', (event) => {
    const firstNetwork = event.networks[0];
    console.log('First network security types:', firstNetwork.securityTypes);
    console.log('First network signal strength:', firstNetwork.rssi);
  });
  await Wifi.startScan();
};
```

# Capawesome April 2025 Update

The Capawesome April update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [March 2025 update](https://capawesome.io/blog/2025-march-update/index.md) to catch up on what shipped last month.

## CLI

### Login via browser

The [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) now supports logging in via the browser. This feature allows you to authenticate your CLI session using a web-based login flow, making it easier to manage your credentials and access the Capawesome Cloud. To get started, simply run the following command in your terminal:

```
npx @capawesome/cli login
```

This will ask you how you would like to authenticate. Select "Login with a web browser" and follow the instructions in your terminal. The CLI will generate a one-time code that you can use to authenticate in your browser.

```
✔ How would you like to authenticate Capawesome CLI?
Login with a web browser

 ╭──────────────────────────────────────╮
 │                                      │
 │  Copy your one-time code: VPD2-VCH4  │
 │                                      │
 ╰──────────────────────────────────────╯


✔ Select Yes to continue in your browser or No to cancel the authentication.
Yes
◐ Opening browser...
◐ Waiting for authentication...
◐ Signing in...
✔ Successfully signed in.
```

## Cloud

### Account linking

You can now set a password for your Capawesome Cloud account if you previously signed up using a third-party provider (e.g., GitHub, or GitLab). This feature also allows you to link one or more third-party accounts to your Capawesome Cloud account. This is useful if you want to use multiple authentication methods or if you want to switch from one provider to another.

Capawesome Cloud Identities

### Open Source Program

We have launched the [Capawesome Cloud Open Source Program](https://capawesome.io/blog/capawesome-cloud-open-source-program/index.md) to support open source projects and developers. This program provides free access to Capawesome Cloud for open source projects, allowing you to use our platform for Over-the-Air (OTA) updates. You can find more information about the program and how to apply in our [blog post](https://capawesome.io/blog/capawesome-cloud-open-source-program/index.md).

### Pricing

We have doubled the MAU limit on all plans for both new and existing customers:

- **Free**: 100 MAU (previously 50)
- **Starter**: 1,000 MAU (previously 500)
- **Professional**: 10,000 MAU (previously 5,000)
- **Team**: 100,000 MAU (previously 50,000)

This means that you can now use Capawesome Cloud for larger projects without having to upgrade to a higher plan. We believe that this change will make it easier for developers to get started with Capawesome Cloud and to scale their projects as needed. You can find more information about our pricing plans on our [pricing page](/#pricing).

### Two-factor authentication

You can now enhance the security of your Capawesome Cloud account by enabling two-factor authentication (2FA). This feature adds an extra layer of protection to your account, requiring a second form of verification in addition to your password. To enable 2FA, go to your [account settings](https://console.cloud.capawesome.io/settings/account) and follow the instructions.

\[

\](/docs/assets/videos/posts/20250430_cloud-2fa.mp4)

## Plugins

### Android Edge-to-Edge Support

The [Capacitor Android Edge-to-Edge Support plugin](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) got several new features and improvements this month.

##### New `enable()` method

The `enable()` method allows you to re-enable the plugin after it has been disabled. This is useful if you want to temporarily disable the edge-to-edge support and then re-enable it later.

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';

const enable = async () => {
  await EdgeToEdge.enable();
};
```

##### New `disable()` method

The `disable()` method allows you to disable the edge-to-edge support. This is useful if you want to temporarily disable the edge-to-edge support without removing the plugin from your project.

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';

const disable = async () => {
  await EdgeToEdge.disable();
};
```

##### New `getInsets()` method

The `getInsets()` method allows you to retrieve the current insets that are applied by the plugin. This is useful if you need to pass these values to other plugins that require insets.

```
import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';

const getInsets = async () => {
  const { top, bottom, right, left } = await EdgeToEdge.getInsets();
  return { top, bottom, right, left };
};
```

### Bluetooth Low Energy

##### Peripheral mode

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) now supports peripheral mode on Android on iOS. This feature allows your app to act as a BLE peripheral, enabling other devices to connect and interact with it. This is useful for applications that need to advertise data or provide services to nearby devices.

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startAdvertising = async () => {
  await BluetoothLowEnergy.startAdvertising({
    name: 'CapBLE',
    services: [
      {
        id: '12345678-1234-1234-1234-1234567890AB',
        characteristics: [
          {
            id: '87654321-4321-4321-4321-BA0987654321',
            descriptors: [], // Descriptors are ignored for now
            permissions: {
              read: true,
              write: true,
            },
            properties: {
              indicate: true,
              notify: true,
              read: true,
              write: true,
            },
          },
        ],
      },
    ],
  });
};
```

The `startAdvertising` method allows you to specify the name of the peripheral and the services it provides. The services can include characteristics with various properties and permissions. You can also stop advertising by calling the `stopAdvertising` method:

```
const stopAdvertising = async () => {
  await BluetoothLowEnergy.stopAdvertising();
};
```

### Contacts

##### New `birthdate` property

The [Capacitor Contacts plugin](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) now supports the `birthdate` property for contacts. This property allows you to store and retrieve the birthdate of a contact, making it easier to manage contact information.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      birthday: {
        day: 1,
        month: 1,
        year: 1990
      },
      givenName: 'John',
      familyName: 'Doe'
    }
  });
};
```

Please note that the `year` property is optional and can be omitted if not needed.

### Firebase

#### Analytics

##### New initiate on-device conversion measurement methods

The [Capacitor Firebase Analytics plugin](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/index.md) now supports multiple new methods for initiating on-device conversion measurement. These methods allow you to initiate conversion measurement using email addresses and phone numbers, as well as their hashed versions. This is useful for tracking conversions and measuring the effectiveness of your marketing campaigns.

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

const initiateOnDeviceConversionMeasurementWithEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithEmailAddress({
    emailAddress: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithPhoneNumber({
    phoneNumber: '+49123456789',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedEmailAddress = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedEmailAddress({
    emailAddressToHash: 'mail@example.com',
  });
};

const initiateOnDeviceConversionMeasurementWithHashedPhoneNumber = async () => {
  await FirebaseAnalytics.initiateOnDeviceConversionMeasurementWithHashedPhoneNumber({
    phoneNumberToHash: '+49123456789',
  });
};
```

### App Check

##### New `tokenChanged` event

The [Capacitor Firebase App Check plugin](https://capawesome.io/docs/sdks/capacitor/firebase/app-check/index.md) now supports the `tokenChanged` event also on Android and iOS. This event is triggered when the App Check token changes, allowing you to handle token updates in your application.

```
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

const addListener = async () => {
  await FirebaseAppCheck.addListener('tokenChanged', (event) => {
    console.log('Token changed:', event.token);
  });
};
```

### Authentication

The [Capacitor Firebase Authentication plugin](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/index.md) got two new features this month.

##### Facebook Limited Login

The plugin now supports Facebook Limited Login. This feature allows you to authenticate users with Facebook while limiting the amount of data shared with your app. This is useful for improving user privacy and security.

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInWithFacebook = async () => {
  const result = await FirebaseAuthentication.signInWithFacebook({
    useLimitedLogin: true,
  });
  return result.user;
};
```

If you don't want to use the limited login feature, you have to request the App Tracking Transparency permission first. This is required by Apple to use Facebook login without limited login:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';


const signInWithFacebook = async () => {
  const { status } = await FirebaseAuthentication.requestAppTrackingTransparencyPermission();
  if (status !== 'granted') {
    throw new Error('App Tracking Transparency permission not granted');
  }
  const result = await FirebaseAuthentication.signInWithFacebook({
    useLimitedLogin: false,
  });
  return result.user;
};
```

##### Disable the Android Credential Manager

Since a few users have reported issues with the new Android Credential Manager (see [#848](https://github.com/capawesome-team/capacitor-firebase/issues/848)), we have added a new property to disable it:

```
import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const signInWithGoogle = async () => {
  const result = await FirebaseAuthentication.signInWithGoogle({
    useCredentialManager: false,
  });
  return result.user;
};
```

By default, the credential manager is enabled. This property is only available on Android.

### ML Kit

#### Barcode Scanning

##### Add torch support

The [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now has its own methods to control the flashlight again. These methods were first removed and migrated to a separate [Capacitor Torch plugin](https://capawesome.io/docs/sdks/capacitor/torch/index.md). However, as this led to various problems, we have decided to bring the methods back into the barcode scanning plugin.

```
import { BarcodeScanning } from '@capacitor-mlkit/barcode-scanning';

const enableTorch = async () => {
  await Torch.enable();
};

const disableTorch = async () => {
  await Torch.disable();
};

const toggleTorch = async () => {
  await Torch.toggle();
};

const isTorchEnabled = async () => {
  const { enabled } = await Torch.isEnabled();
  return enabled;
};

const isTorchAvailable = async () => {
  const { available } = await Torch.isAvailable();
  return available;
};
```

The methods are available on Android and iOS.

##### New `3840x2160` resolution

The [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now supports the `3840x2160` resolution for scanning barcodes. This resolution is available on Android and iOS devices with a camera that supports this resolution. The new resolution allows for higher quality scans and improved performance in low-light conditions.

```
import { BarcodeScanning, Resolution } from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  await BarcodeScanner.startScan({
    resolution: Resolution['3840x2160'],
  });
};
```

#### Subject Segmentation

We have published a new [Subject Segmentation](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/index.md) plugin. This plugin allows you to segment subjects in images, making it easier to create custom image processing applications. The plugin is available on Android.

```
import { SubjectSegmentation } from '@capacitor-mlkit/subject-segmentation';

const processImage = async () => {
  const { path } = await SubjectSegmentation.processImage({
    path: 'path/to/image.jpg',
    confidence: 0.7,
  });
  return path;
};
```

The plugin provides a simple API for processing images and returning the segmented image. You can adjust the confidence level to control the sensitivity of the segmentation.

### Printer

##### New `printBase64(...)` method

The [Capacitor Printer plugin](https://capawesome.io/docs/sdks/capacitor/printer/index.md) now supports printing base64 encoded files. This feature allows you to print files that are not available on the device's file system, such as files that are generated in memory or downloaded from a remote server. The new `printBase64(...)` method accepts a base64 encoded string and prints it using the default printer.

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printBase64 = async () => {
  await Printer.printBase64({
    name: 'My Document',
    data: 'JVBERi0...',
  });
}
```

The method is available on Android and iOS. Please note that large base64 strings may lead to app crashes or performance issues. We therefore recommend using this feature only for small files or images. For larger files, consider saving them to the device's file system and using the `printFile(...)` method.

##### New `printFile(...)` method

The [Capacitor Printer plugin](https://capawesome.io/docs/sdks/capacitor/printer/index.md) now also supports printing files (including images) from the device's file system. The new `printFile(...)` method accepts a file path and prints it using the default printer.

```
import { Printer } from '@capawesome-team/capacitor-printer';

const printFile = async () => {
  await Printer.printFile({
    mimeType: 'application/pdf',
    path: '/path/to/file.pdf',
  });
};
```

The method is available on Android and iOS.

# Capawesome August 2025 Update

The Capawesome August update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [July 2025 update](https://capawesome.io/blog/2025-july-update/index.md) to catch up on what shipped last month.

## Cloud

##### SOC 2 Type 2 Compliance

We are excited to announce that Capawesome Cloud is now SOC 2 Type 2 compliant. This means that we have implemented rigorous security controls and processes to protect your data and ensure the highest level of privacy and security.

Check out our [announcement post](https://capawesome.io/blog/capawesome-cloud-soc-2-type-2-compliance/index.md) for more details on our SOC 2 Type 2 compliance.

## Plugins

### Accelerometer

We have published a new [Capacitor Accelerometer plugin](https://capawesome.io/docs/sdks/capacitor/accelerometer/index.md) that allows you to access the device's accelerometer sensor data on iOS and Android.

```
import { Accelerometer } from '@capawesome-team/capacitor-accelerometer';

const getMeasurement = async () => {
  const measurement = await Accelerometer.getMeasurement();
  console.log("X: ", measurement.x);
  console.log("Y: ", measurement.y);
  console.log("Z: ", measurement.z);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/accelerometer/index.md) for more information on how to configure and use the plugin.

### Android Edge-to-Edge Support

The [Capacitor Android Edge-to-Edge Support plugin](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) has received small bug fixes. Please check out the [CHANGELOG.md](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/#changelog) for more details.

### Asset Manager

The [Capacitor Asset Manager plugin](https://capawesome.io/docs/sdks/capacitor/asset-manager/index.md) has received small bug fixes. Please check out the [CHANGELOG.md](https://capawesome.io/docs/sdks/capacitor/asset-manager/#changelog) for more details.

### Audio Recorder

The [Capacitor Audio Recorder plugin](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) now supports setting `audioSessionCategoryOptions` on iOS when starting a recording. This allows you to customize the audio session behavior, such as allowing mixing with other audio sources or enabling Bluetooth support.

```
import { AudioRecorder, AudioSessionCategoryOption } from '@capawesome-team/capacitor-audio-recorder';

const startRecording = async () => {
  await AudioRecorder.startRecording({
    audioSessionCategoryOptions: [AudioSessionCategoryOption.DuckOthers],
  });
};
```

### Firebase

All [Firebase plugins](https://capawesome.io/docs/sdks/capacitor/firebase/index.md) have been updated and received several small bug fixes. Please check out the `CHANGELOG.md` files of the respective plugins for more details.

### NFC

The [Capacitor NFC plugin](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) has received several improvements and bug fixes. Notably, we have added a new `mapUriIdentifierCodeToString` utility function that maps URI identifier codes to their corresponding string representations. Additionally, the `convertBytesToString` method now accepts `Uint8Array` types, making it more versatile.

```
import { NfcUtils, UriIdentifierCode } from '@capawesome-team/capacitor-nfc';

const mapUriIdentifierCodeToString = () => {
  const utils = new NfcUtils();
  const { prefix } = utils.mapUriIdentifierCodeToString({ identifierCode: UriIdentifierCode.HttpsWww });
  console.log(prefix); // Outputs: "https://www."
};

const convertBytesToString = () => {
  const utils = new NfcUtils();
  const { text } = utils.convertBytesToString({ bytes: [72, 101, 108, 108, 111] });
  console.log(text); // Outputs: "Hello"
};
```

### Pedometer

We have published a new [Capacitor Pedometer plugin](https://capawesome.io/docs/sdks/capacitor/pedometer/index.md) that allows you to access step count and distance data from the device's built-in pedometer on iOS and Android.

```
import { Pedometer } from '@capawesome-team/capacitor-pedometer';

const getMeasurement = async () => {
  const { measurement } = await Pedometer.getMeasurement();
  console.log("Average Active Pace:", measurement.averageActivePace);
  console.log("Current Cadence:", measurement.currentCadence);
  console.log("Current Pace:", measurement.currentPace);
  console.log("Distance:", measurement.distance);
  console.log("Floors Ascended:", measurement.floorsAscended);
  console.log("Floors Descended:", measurement.floorsDescended);
  console.log("Number of Steps:", measurement.numberOfSteps);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/pedometer/index.md) for more information on how to configure and use the plugin.

### RealtimeKit

We have published a new [Capacitor RealtimeKit plugin](https://capawesome.io/docs/sdks/capacitor/realtimekit/index.md) that provides real-time communication capabilities for your Capacitor apps using the [RealtimeKit SDK](https://docs.realtime.cloudflare.com/). With RealtimeKit, you can easily integrate programmable, and easily customizable live video and voice.

```
import { RealtimeKit } from '@capawesome-team/capacitor-realtimekit';

const startMeeting = async () => {
  await RealtimeKit.startMeeting({
    authToken: 'your-auth-token',
    enableAudio: true,
    enableVideo: true,
  });
};
```

### Screen Orientation

The [Capacitor Screen Orientation plugin](https://capawesome.io/docs/sdks/capacitor/screen-orientation/index.md) has received small bug fixes. Please check out the [CHANGELOG.md](https://capawesome.io/docs/sdks/capacitor/screen-orientation/#changelog) for more details.

### Share Target

We have published a new [Capacitor Share Target plugin](https://capawesome.io/docs/sdks/capacitor/share-target/index.md) that allows your app to receive shared content from other apps on Android, iOS and Web. This plugin enables your app to appear in the system share sheet, allowing users to share text, images, URLs, and other types of content directly to your app.

Here's a simple example of how to use the Share Target plugin to listen for shared content:

```
import { ShareTarget } from '@capawesome-team/capacitor-share-target';

const addListener = async () => {
    await ShareTarget.addListener('shareReceived', (event) => {
        console.log('Share received:', event);

        // Handle shared files
        if (event.files) {
          event.files.forEach(async (fileUrl) => {
            const response = await fetch(fileUrl);
            const blob = await response.blob();
            // Process the file...
          });
        }
    });
};
```

Make sure to check out the [documentation](https://capawesome.io/docs/sdks/capacitor/share-target/index.md) for more information on how to configure and use the plugin.

### Speech Recognition

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) now supports a `soundLevel` listener that provides real-time updates on the sound level during speech recognition. This can be useful for visualizing the input volume or for implementing custom UI feedback.

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const addListener = () => {
  SpeechRecognition.addListener('soundLevel', (event) => {
    console.log('Sound level:', event.level);
  });
};
```

### Speech Synthesis

The [Capacitor Speech Synthesis plugin](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) has been updated to include `pause` and `resume` methods. This allows you to pause and resume speech playback, providing more control over the speech synthesis experience.

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const pause = async () => {
  await SpeechSynthesis.pause();
};

const resume = async () => {
  await SpeechSynthesis.resume();
};
```

### Sqlite

The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) has received small bug fixes. Please check out the [CHANGELOG.md](https://capawesome.io/docs/sdks/capacitor/sqlite/#changelog) for more details.

# Capawesome December 2025 Update

The Capawesome December update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [November 2025 update](https://capawesome.io/blog/2025-november-update/index.md) to catch up on what shipped last month.

## Cloud

### Build Stacks

We are excited to announce the launch of the new `macos-tahoe` build stack for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). This build stack provides support for Xcode 26.2, enabling you to build your iOS applications with the latest tools and features from Apple.

The `macos-tahoe` build stack runs on macOS 26 and includes updated versions of key development tools. In addition to Xcode 26.2, it comes with Fastlane 2.229.1, npm 11.6.2, and Java 17/21 (with 21 as the default). Node.js versions 20, 22, and 24 are supported, with 24 as the default.

This new build stack ensures you can take advantage of the latest iOS SDK features and improvements. You can select the `macos-tahoe` build stack in your build configuration to start using Xcode 26.2 today. For more information, check out the [Build Stacks documentation](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md).

### Teams

We are excited to introduce Teams to [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md)! This new feature enables organizations to organize members and control access to specific apps, providing better structure and security for larger teams.

Teams function as access control groups where you can assign members and apps together. Each team can have multiple members, and members can belong to multiple teams. When a member is part of a team, they automatically gain access to all apps assigned to that team. Organization Owners and Admins maintain access to all apps regardless of team membership.

\[

\](/docs/assets/videos/posts/20251231_cloud-teams.mp4)

To get started with Teams, navigate to the Teams page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/teams). Check out the [Teams documentation](https://capawesome.io/docs/cloud/organizations/teams/index.md) to learn more.

## Plugins

All Capawesome plugins have been updated to support Capacitor 8! This major update brings improved performance, better error handling, and updated dependencies across all platforms. We've also updated all plugin dependencies to their latest stable versions to ensure compatibility and security.

Check out our [Capacitor 8 migration guide](https://capawesome.io/blog/updating-to-capacitor-8/index.md) for detailed information about breaking changes and how to update your applications. The guide includes step-by-step instructions for migrating each plugin to the new version.

### Audio Player

The [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) now supports remote URLs on Android, expanding playback capabilities across all platforms. Previously limited to web assets on Android, the plugin now allows you to play audio files from remote servers, matching the functionality available on iOS and Web.

This enhancement means you can stream audio content directly from your CDN or API without needing to bundle files with your application. Both the `src` parameter for web assets and remote URLs, and the `uri` parameter for local file paths are now fully supported on Android, providing consistent behavior across all platforms.

### Age Signals

The [Capacitor Age Signals plugin](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) has been enhanced with new testing methods for Android and an eligibility check for iOS. Three testing methods—[`setUseFakeManager()`](https://capawesome.io/docs/sdks/capacitor/age-signals/#setusefakemanager), [`setNextAgeSignalsResult(...)`](https://capawesome.io/docs/sdks/capacitor/age-signals/#setnextagesignalsresult), and [`setNextAgeSignalsException(...)`](https://capawesome.io/docs/sdks/capacitor/age-signals/#setnextagesignalsexception)—enable comprehensive testing of age-related features without requiring actual Google Play integration.

A new [`checkEligibility()`](https://capawesome.io/docs/sdks/capacitor/age-signals/#checkeligibility) method is now available on iOS to determine if users are eligible for age-gated features based on their region:

```
import { AgeSignals } from '@capawesome/capacitor-age-signals';

const checkEligibility = async () => {
  const result = await AgeSignals.checkEligibility();
  console.log('Eligible:', result.eligible);
};
```

### PostHog

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) now includes consent management and cookieless tracking features, giving you more control over user privacy and GDPR compliance. Three new methods—[`optIn()`](https://capawesome.io/docs/sdks/capacitor/posthog/#optin), [`optOut()`](https://capawesome.io/docs/sdks/capacitor/posthog/#optout), and [`isOptOut()`](https://capawesome.io/docs/sdks/capacitor/posthog/#isoptout)—manage user consent for event tracking:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const handleConsent = async () => {
  await Posthog.optIn(); // User accepts tracking
  await Posthog.optOut(); // User rejects tracking

  const result = await Posthog.isOptOut();
  console.log('Opted out:', result.optedOut);
};
```

The plugin also supports cookieless tracking on Web, enabling privacy-focused analytics without browser cookies. Configure the [`setup(...)`](https://capawesome.io/docs/sdks/capacitor/posthog/#setup) method with `cookielessMode` set to `always` for continuous cookieless tracking or `on_reject` to switch to cookieless mode when users opt out. This feature requires cookieless mode to be enabled in your PostHog project settings.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) now includes a new [`getProductById(...)`](https://capawesome.io/docs/sdks/capacitor/purchases/#getproductbyid) method that retrieves detailed information about a specific in-app product. This method simplifies product queries by allowing you to fetch details for a single product without needing to load your entire product catalog.

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const getProduct = async () => {
  const result = await Purchases.getProductById({
    productId: 'com.example.premium'
  });

  console.log('Product:', result.product.displayName);
  console.log('Price:', result.product.price);
  console.log('Currency:', result.product.currencyCode);
};
```

The method returns comprehensive product information including the display name, description, localized pricing, currency code, and product type. This is particularly useful when you need to display pricing information for a specific product or validate product availability before presenting purchase options to users.

This method is available on Android and iOS 15.0+.

### Superwall

We are excited to announce the initial release of the [Capacitor Superwall plugin](https://capawesome.io/docs/sdks/capacitor/superwall/index.md)! This unofficial Capacitor plugin integrates the Superwall SDK into your mobile applications, providing powerful monetization and user engagement features for managing in-app subscriptions and paywalls.

The plugin enables you to display remotely-configured paywalls without app updates, control feature access based on subscription status, and track user analytics across platforms. It includes built-in A/B testing support to optimize conversion rates and works seamlessly on both Android and iOS. Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/superwall/index.md) to learn more about getting started with the Superwall plugin.

# Capawesome February 2025 Update

The Capawesome February update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [January 2025 update](https://capawesome.io/blog/2025-january-update/index.md) to catch up on what shipped last month.

## Cloud

### Advanced Filtering

We have added advanced filtering to the [Capawesome Cloud Console](https://console.cloud.capawesome.io/). This feature allows you to filter your bundles by various criteria, such as ID, channel, artifact type, and artifact status, making it easier to manage your live updates.

\[

\](/docs/assets/videos/posts/cloud-advanced-filtering.mp4)

### Force Code Signing

You can now enforce code signing for all bundles in your app. This feature ensures that all bundles are signed with a private key before they are uploaded to the Capawesome Cloud, making sure that no unsigned bundles are distributed to your users. You can enable this feature in the settings of your app through the [Capawesome Cloud Console](https://console.cloud.capawesome.io/apps).

\[

\](/docs/assets/videos/posts/cloud-app-force-bundle-signatures.mp4)

### Self-Hosting

Check out the new [Self-Hosting](https://capawesome.io/docs/cloud/live-updates/self-hosting/index.md) guide to learn how to self-host your Live Updates. This feature allows you to host the bundles on your server instead of Capawesome Cloud. This can be useful if you have specific security requirements, or if you want to avoid being affected by data transfer or storage limitations.

## Plugins

### Android Edge-to-Edge Support

We have published a new [Capacitor Android Edge-to-Edge Support plugin](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) to support [edge-to-edge](https://developer.android.com/develop/ui/views/layout/edge-to-edge) display on Android. This has been a real problem for many users who have updated to Capacitor 7, as Android 15 enforces the edge-to-edge display. This causes the web view to be displayed behind the status bar and navigation bar, which can lead to layout issues. The plugin restores the previous behavior and ensures that the web view is displayed correctly.

### Firebase

#### App Check

The [Capacitor Firebase App Check plugin](https://capawesome.io/docs/sdks/capacitor/firebase/app-check/index.md) now supports all available providers. For this, a new `provider` option has been added to the `initialize(...)` method.

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

const initialize = async () => {
  await FirebaseAppCheck.initialize({
    provider: new ReCaptchaV3Provider('myKey');
  });
};
```

#### Crashlytics

##### Custom Keys And Values

The [Capacitor Firebase Crashlytics plugin](https://capawesome.io/docs/sdks/capacitor/firebase/crashlytics/index.md) now supports custom keys and values for the `recordException(...)` method. This allows you to attach additional information to an exception, such as user-specific data or metadata, making it easier to debug and analyze non-fatal exceptions.

```
import { FirebaseCrashlytics } from '@capacitor-firebase/crashlytics';

const recordException = async () => {
  await FirebaseCrashlytics.recordException({
    message: 'My error message',
    customKeysAndValues: [
      {
        key: 'customKey1',
        value: 'customValue1',
        type: 'string',
      },
      {
        key: 'customKey2',
        value: 123,
        type: 'int',
      }
    ],
  });
};
```

### Live Update

##### Code Signing for Self-Hosted Bundles

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) now supports code signing for self-hosted bundles. Code signing was previously only available for bundles hosted on Capawesome Cloud. With this update, you can now also host your bundles on your server and ensure that only signed bundles are installed on your users' devices.

```
import { LiveUpdate } from '@capawesome-team/capacitor-live-update';

const downloadLatestBundle = async () => {
  // Fetch the latest bundle from Capawesome Cloud
  const { bundleId, downloadUrl, signature } = await LiveUpdate.fetchLatestBundle();
  // Download the bundle from your server
  await LiveUpdate.downloadBundle({
    bundleId,
    signature,
    url: downloadUrl,
  });
};
```

### ML Kit

#### Barcode Scanning

##### Auto Focus

The [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now also supports auto-focus on iOS. This feature enables the camera to focus automatically on the barcode, making it easier to scan barcodes from various distances. You don't need to take any action to activate this feature; it is enabled automatically when you initiate the barcode scanning process.

##### Web Support

The [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now also supports the web platform. You can use the plugin in your web app to scan barcodes directly from the browser thanks to the [Barcode Detection API](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API).

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  // Add the `barcodeScanned` listener
  const listener = await BarcodeScanner.addListener(
    'barcodeScanned',
    async result => {
      console.log(result.barcode);
    },
  );

  // Start the barcode scanner
  await BarcodeScanner.startScan({
    videoElement: document.getElementById('video'),
  });
};
```

### Speech Synthesis

##### New `synthesizeToFile(...)` method

The [Capacitor Speech Synthesis plugin](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) now supports the `synthesizeToFile(...)` method. This method allows you to synthesize text to an audio file and save it to the device. The audio file can be played back or shared with other apps.

```
import { SpeechSynthesis } from '@capawesome-team/capacitor-speech-synthesis';

const synthesizeToFile = async () => {
  // Add an utterance to the utterance queue to be synthesized to a file
  const { path, utteranceId } = await SpeechSynthesis.synthesizeToFile({
    language: 'en-US',
    pitch: 1.0,
    queueStrategy: QueueStrategy.Add,
    rate: 1.0,
    text: 'Hello, World!',
    voiceId: 'com.apple.ttsbundle.Samantha-compact',
    volume: 1.0,
  });
  // Wait for the utterance to finish
  await new Promise(resolve => {
    void SpeechSynthesis.addListener('end', event => {
      if (event.utteranceId === utteranceId) {
        resolve();
      }
    });
  });
  // Return the path to the synthesized audio file
  return path;
};
```

# Capawesome January 2025 Update

The Capawesome January update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [December 2024 update](https://capawesome.io/blog/2024-december-update/index.md) to catch up on what shipped last month.

## CLI

### Custom Properties

The Capawesome CLI now supports custom properties for the `apps:bundles:create` command:

```
npx @capawesome/cli apps:bundles:create --custom-property version=1.1.0 --custom-property silentUpdate=true
```

Custom properties allow you to store additional information in a bundle and can be retrieved by the [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md). This allows you to customize the behavior of your app for specific bundles.

## Cloud

### Landing Page

We've just launched our brand new landing page for Capawesome Cloud. The new landing page is available at [capawesome.io](/) and provides an overview of all features and benefits of Capawesome Cloud, including customer testimonials and pricing information. The Capawesome Cloud Console, which was previously accessible at [console.cloud.capawesome.io](https://console.cloud.capawesome.io/), has been moved to [console.cloud.capawesome.io](https://console.cloud.capawesome.io/).

Do you like the new landing page? Let us know what you think!

### GitHub Action

The [Cloud Live Update Action](https://github.com/capawesome-team/cloud-live-update-action) now uses the latest version of the Capawesome CLI. This update includes various improvements and bug fixes. The Cloud Live Update Action allows you to deploy a live update to the Capawesome Cloud directly from your GitHub Actions workflow:

```
- uses: capawesome-team/cloud-live-update-action@v0.0.3
  with:
    # The Capawesome Cloud app ID.
    # Required.
    appId: ''
    # The channel to deploy the update to.
    channel: ''
    # The path to the bundle to upload. Must be a folder or zip archive.
    # Required.
    path: ''
    # The Capawesome Cloud API token.
    # Required.
    token: ''
```

## Plugins

All plugins now support Capacitor 7 and the Swift Package Manager (SPM). This means that you can now use the plugins with the latest version of Capacitor and add them to your Xcode project using SPM. Read on to learn more about the latest changes to our plugins.

Breaking Changes

We have published some breaking changes to our plugins this month. Please make sure to carefully review the changes before updating your plugins. You can find more information about the breaking changes in the respective `BREAKING.md` files in the plugin repositories.

### App Shortcuts

##### New `icon` option

The [Capacitor App Shortcuts plugin](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/index.md) now supports the `icon` option. This option allows you to specify an icon for the shortcut:

```
import { Capacitor } from '@capacitor/core';
import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const set = async () => {
  await AppShortcuts.set({
    shortcuts: [
      {
        id: 'feedback',
        title: 'Feedback',
        description: 'Send feedback to the app developers',
        icon: Capacitor.getPlatform() === 'ios' ? 6 : 17301547,
      }
    ],
  });
};
```

The `icon` option accepts a number. On Android, the icon is the constant value of the [`R.drawable`](https://developer.android.com/reference/android/R.drawable) enum. On iOS, the icon is the constant value of the [`UIApplicationShortcutIcon.IconType`](https://developer.apple.com/documentation/uikit/uiapplicationshortcuticon/icontype) enum.

### Firebase

#### Cloud Firestore

##### New `getCountFromServer` method

The [Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) plugin now supports a `getCountFromServer` method. This method allows you to get the number of documents in a collection from the server:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getCountFromServer = async () => {
  const { count } = await FirebaseFirestore.getCountFromServer({
    reference: 'users',
  });
  return count;
};
```

### Live Update

##### Automatic rollbacks disabled by default

The default value of the `readyTimeout` configuration option has been changed from `10000` to `0` to disable the timeout by default. This should make it easier to get started with the plugin. This feature has often caused confusion and issues for users who were not aware of the timeout. However, it is strongly **recommended** to configure this option so that the plugin can roll back to the default bundle in case of problems:

```
{
  "plugins": {
    "LiveUpdate": {
      "readyTimeout": 10000
    }
  }
}
```

##### New `ReadyResult` type

The `ready()` method now returns a `ReadyResult` object with the following properties:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const ready = async () => {
  const result = await LiveUpdate.ready();
  console.log('Previous Bundle ID: ', result.previousBundleId);
  console.log('Current Bundle ID: ', result.currentBundleId);
  console.log('Rollback performed? ', result.rollback);
};
```

This change allows you to get more information about the current state of the app after the `ready()` method has been called. For example, you can display a message to the user if an update has failed.

##### Custom properties

The `fetchLatestBundle(...)` method now also returns the custom properties of the latest bundle:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const fetchLatestBundle = async () => {
  const { customProperties } = await LiveUpdate.fetchLatestBundle();
  console.log('Custom Properties: ', customProperties);
};
```

This allows you to customize the behavior of your app based on the custom properties of the latest bundle. For example, you could use a custom property `silentUpdate` to decide whether the user should be asked before downloading the bundle or not.

##### New `downloadBundleProgress` listener

The `downloadBundle(...)` method now emits a `downloadBundleProgress` event with the download progress:

```
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const downloadBundle = async () => {
  // Listen for download progress
  await LiveUpdate.addListener('downloadBundleProgress', (event) => {
    console.log('Bundle ID: ', event.bundleId);
    console.log('Progress: ', event.progress);
    console.log('Downloaded bytes: ', event.downloadedBytes);
    console.log('Total bytes: ', event.totalBytes);
  });
  // Download the latest bundle
  await LiveUpdate.downloadBundle();
};
```

This change allows you to display a progress bar or other UI elements to the user while the bundle is being downloaded.

### ML Kit

#### Barcode Scanning

##### New `resolution` option

The [Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now supports a `resolution` option. This option allows you to specify the resolution of the barcode scanning process:

```
import { BarcodeScanner, Resolution } from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  await BarcodeScanner.startScan({
    resolution: Resolution['1280x720'],
  });
};
```

The possible values for the `resolution` option are:

- `640x480`
- `1280x720`
- `1920x1080`

### Screenshot

We have published a new [Capacitor Screenshot plugin](https://capawesome.io/docs/sdks/capacitor/screenshot/index.md). The Screenshot plugin allows you to take screenshots of the current screen and can be used for various purposes, such as error reporting or sharing content.

```
import { Screenshot } from '@capawesome/capacitor-screenshot';

const take = async () => {
  const { uri } = await Screenshot.take();
  console.log('Screenshot saved at:', uri);
};
```

# Capawesome July 2025 Update

The Capawesome July update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [June 2025 update](https://capawesome.io/blog/2025-june-update/index.md) to catch up on what shipped last month.

## Blog

We have made several updates to our blog, including new articles and tutorials that cover various topics related to Capacitor and our plugins. Be sure to check out the latest posts for valuable insights and tips. Here are some highlights:

- [Encrypting SQLite databases in Capacitor](https://capawesome.io/blog/encrypting-capacitor-sqlite-database/index.md)
- [Announcing the SQLite Plugin for Capacitor](https://capawesome.io/blog/announcing-the-capacitor-sqlite-plugin/index.md)
- [Exploring the Capacitor Secure Preferences API](https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/index.md)

Besides these articles, we have also started a new series of showcases where we highlight some of the best apps built with Capacitor. These showcases will provide insights into how developers are using Capacitor to create amazing applications. Here are the first few showcases:

- [Showcase: MyBodyTutor - A Personalized Nutrition and Weight Loss Coaching App](https://capawesome.io/blog/showcase-mybodytutor/index.md)
- [Showcase: CostPal - Price tracking app for Costco](https://capawesome.io/blog/showcase-costpal/index.md)

Make sure to check them out!

## Cloud

##### New `Billing` role

We have introduced a new `Billing` role in Capawesome Cloud. This role allows users to manage billing-related tasks without granting full administrative access. Users with the `Billing` role can view and manage billing information, including invoices and payment methods.

Check out the [documentation](https://capawesome.io/docs/cloud/organizations/memberships/index.md) for more details on the `Billing` role and how to assign it to users.

## Plugins

### Barometer

We have released a new [Capacitor Barometer plugin](https://capawesome.io/docs/sdks/capacitor/barometer/index.md) for Android and iOS. This plugin allows you to access the device's barometer sensor, providing real-time atmospheric pressure data. You can use this data for various applications, such as weather forecasting or altitude measurement.

```
import { Barometer } from '@capawesome-team/capacitor-barometer';

const getMeasurement = async () => {
  const { measurement } = await Barometer.getMeasurement();
  console.log('Current atmospheric pressure:', measurement.pressure, 'hPa');
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/barometer/index.md) for more details on how to get started with the Barometer plugin.

### Bluetooth Low Energy

##### New `onConnectionStateChange` method in headless task

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) has been updated with a new `onConnectionStateChange` method in the `BluetoothLowEnergyHeadlessTask` class. This method allows you to run your own native code when the connection state of a Bluetooth device changes. This is useful for handling connection events in the background, such as when a device disconnects or reconnects.

```
import android.bluetooth.BluetoothGatt;
import androidx.annotation.NonNull;

public class BluetoothLowEnergyHeadlessTask {
  public void onConnectionStateChange(@NonNull BluetoothGatt gatt, int status, int newState) {
    // Your code here
  }
}
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#headless-task) for more details on how to use the `onConnectionStateChange` method in your headless task.

### File Compressor

##### `width` and `height` options

The [Capacitor File Compressor plugin](https://capawesome.io/docs/sdks/capacitor/file-compressor/index.md) has been updated to support the `width` and `height` options when compressing images. This allows you to resize images while compressing them, which can help reduce file size without losing too much quality.

```
import { FileCompressor } from '@capawesome-team/capacitor-file-compressor';

const compressImage = async () => {
  const { path } = await FileCompressor.compressImage({
    mimeType: 'image/jpeg',
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000485',
    quality: 0.7,
    height: 1000,
    width: 1000,
  });
  return path;
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/file-compressor/#compressimage) for more details on how to use the `width` and `height` options when compressing images.

### Firebase

#### Authentication

##### `authDomain` configuration option

The [Capacitor Firebase Authentication plugin](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/index.md) has been updated to include a new `authDomain` configuration option. This option allows you to specify the authentication domain for your Firebase project, which is required for certain authentication methods.

```
{
  "plugins": {
    "FirebaseAuthentication": {
      "authDomain": "your-app.firebaseapp.com"
    }
  }
}
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/#configuration) for more details on how to configure the `authDomain` option.

#### Cloud Firestore

##### `SetOptions` interface

The [Capacitor Firebase Cloud Firestore plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) has been updated to include a new `SetOptions` interface. This interface allows you to specify options when setting documents in Firestore, such as merging data.

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};
```

For more details on how to use the `SetOptions` interface, check out the [documentation](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/#setoptions).

### ML Kit

#### Document Scanner

We have released a new [Document Scanner](https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner/index.md) plugin for Android based on the [ML Kit Document Scanner](https://developers.google.com/ml-kit/vision/doc-scanner) API. This plugin allows you to scan documents using the device's camera or import them from the gallery. It supports various result formats, including JPEG and PDF.

```
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const scanDocument = async () => {
  const result = await DocumentScanner.scanDocument({
    galleryImportAllowed: true,
    pageLimit: 5,
    resultFormats: 'JPEG_PDF',
    scannerMode: 'FULL',
  });

  console.log('Result:', result);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner/index.md) for more details on how to use the Document Scanner plugin.

### libSQL

We have released a new [Capacitor libSQL plugin](https://capawesome.io/docs/sdks/capacitor/libsql/index.md) for Android and iOS. This plugin provides a powerful and efficient way to manage SQLite databases using the [libSQL](https://docs.turso.tech/libsql) engine, which is a fork of SQLite from the team behind [Turso](https://turso.tech/).

```
import { Libsql } from '@capawesome-team/capacitor-libsql';

const insertUser = async (user: { id: number; name: string }) => {
  // Open the database
  const { connectionId } = await Libsql.connect({
    database: 'my-database',
  });
  // Insert a new row
  await Libsql.execute({
    connectionId,
    statement: 'INSERT INTO users (id, name) VALUES (?, ?)',
    values: [user.id, user.name],
  });
  // Close the database
  await Libsql.close({ connectionId });
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/libsql/index.md) for more details on how to get started with the libSQL plugin.

### Live Update

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) has received a small bug fix to ensure that missing bundle files are handled correctly. This fix improves the reliability of the live update process, ensuring that your app can seamlessly update without issues.

Make sure to update your Live Update plugin to the latest version to benefit from this fix.

### PostHog

##### New configuration options

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) has been updated with new configuration options. You can now set the `apiKey` and `host` when initializing the plugin, allowing you to track advanced analytics events like app installations and more.

```
{
  "plugins": {
    "Posthog": {
      "apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      "host": 'https://eu.i.posthog.com'
    }
  }
}
```

This also means that you don't need to call the `setup(...)` method anymore, as the plugin will automatically initialize with the provided configuration.

### Speech Recognition

##### Punctuation support

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) has been updated to support punctuation in transcriptions. Just set the `enableFormatting` option to `true` when starting the speech recognition session, and the plugin will automatically format the transcriptions with punctuation.

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

const startListening = async () => {
  await SpeechRecognition.startListening({
    enableFormatting: true,
  });
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) for more details.

### SQLite

We have published a new [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) for Capacitor. This plugin provides a powerful and efficient way to manage SQLite databases on Android, iOS and web. It supports various features such as encryption, migrations, and more.

Here's a quick example of how to use the SQLite plugin to open a database and insert a new row:

```
import { SQLite } from '@capawesome-team/capacitor-sqlite';

const insertUser = async (user: { id: number; name: string }) => {
  // Open the database
  const { databaseId } = await SQLite.open({ 
    path: 'db.sqlite3',
    upgradeStatements: [
      {
        version: 1,
        statements: [
          'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)',
        ]
      }
    ],
  });
  // Insert a new row
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, email) VALUES (?, ?)',
    values: ['John Doe', 'john.doe@example.com']
  });
  // Close the database
  await SQLite.close({ databaseId });
};
```

Check out the [announcement post](https://capawesome.io/blog/announcing-the-capacitor-sqlite-plugin/index.md) for more details on how to get started with the SQLite plugin.

# Capawesome June 2025 Update

The Capawesome June update is here! This update includes new features and improvements for the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md).

In case you missed it, check out the [May 2025 update](https://capawesome.io/blog/2025-may-update/index.md) to catch up on what shipped last month.

## CLI

### Uploading bundles larger than 100 MB

Starting with version 1.13.0, the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) now supports uploading bundles larger than 100 MB. This feature is particularly useful for apps with large assets or dependencies. The CLI automatically splits the bundle into smaller chunks and uploads them in parallel, ensuring a faster and more reliable upload process.

## Plugins

We have made several improvements to our plugins this month, enhancing their functionality and usability. This section highlights the most significant changes.

### App Shortcuts

##### Support Base64 encoded icons

The [Capacitor App Shortcuts plugin](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/index.md) has been updated to support Base64 encoded icons on Android. This allows developers to use icons directly from their code without needing to store them as separate files, simplifying the development process and allowing for more dynamic icon management.

### Biometrics

##### Add `enroll()` method

The [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) now supports prompting users to enroll their biometrics. The new `enroll()` method allows developers to trigger the biometric enrollment process, enabling users to set up their biometrics directly from the app. This feature enhances user experience by making it easier to enroll biometrics without navigating to device settings.

```
import { Biometrics } from '@capawesome/capacitor-biometric';

const enroll = async () => {
  try {
    await Biometrics.enroll();
    console.log('Biometric enrollment successful');
  } catch (error) {
    console.error('Biometric enrollment failed:', error);
  }
};
```

This method is only available on Android.

### File Picker

##### Support for iOS for the `copyFile(...)` method

The [Capacitor File Picker plugin](https://capawesome.io/docs/sdks/capacitor/file-picker/index.md) has been enhanced with support for the `copyFile(...)` method on iOS. This feature allows developers to copy files within the app's file system, making it easier to manage picked files and organize them as needed.

```
import { FilePicker } from '@capawesome/capacitor-file-picker';
import { Directory, Filesystem } from '@capacitor/filesystem';

const copyFile = async () => {
  const { uri: toUri } = await Filesystem.getUri({
    directory: Directory.Documents,
    path: 'old/file.txt',
  });
  const { uri: fromUri } = await Filesystem.getUri({
    directory: Directory.Documents,
    path: 'new/file.txt',
  });
  await FilePicker.copyFile({
    from: fromUri,
    to: toUri,
    overwrite: true,
  });
};
```

# Capawesome March 2025 Update

The Capawesome March update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [February 2025 update](https://capawesome.io/blog/2025-february-update/index.md) to catch up on what shipped last month.

## Cloud

### Console

#### Force Code Signing

You can now enforce code signing for all bundles in your app. This feature ensures that all bundles are signed with a private key before they are uploaded to the Capawesome Cloud, making sure that no unsigned bundles are distributed to your users. You can enable this feature in the settings of your app through the [Capawesome Cloud Console](https://console.cloud.capawesome.io/apps).

\[

\](/docs/assets/videos/posts/cloud-force-code-signing.mp4)

#### Git Integration

Capawesome Cloud offers a lightweight Git integration that allows you to link your bundles to Git commits. This way, you can easily track which version of your app is currently live and which changes have been made since the last update. To enable Git integration, simply edit the app in the Capawesome Cloud Console, enable the Git integration toggle and provide the URL of the Git repository. After that, you can use the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) to create a new bundle and link it to a specific commit:

```
npx @capawesome/cli apps:bundles:create --commit-message "feat: support in-app purchases" --commit-ref "main" --commit-sha "b0cb01e"
```

Check out the [documentation](https://capawesome.io/docs/cloud/live-updates/integrations/index.md) for more information.

### GitHub Action

#### Git Integration

The [GitHub Action](https://github.com/capawesome-team/cloud-live-update-action) also supports the new Git integration feature.

## Plugins

### App Shortcuts

The [Capacitor App Shortcuts plugin](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/index.md) received various bug fixes and improvements.

### Audio Recorder

We have published a new [Capacitor Audio Recorder plugin](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md). This plugin allows you to record audio using the device's microphone. You can start, pause, resume, and stop the recording and get the audio blob or URI. The plugin is available on Android, iOS and Web.

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { NativeAudio } from '@capacitor-community/native-audio';

const startRecording = async () => {
  await AudioRecorder.startRecording();
};

const stopRecording = async () => {
  // Stop recording and get the audio blob or URI
  const { blob, uri } = await AudioRecorder.stopRecording();
  // Play the audio
  if (blob) {
    // Only available on Web
    const audio = new Audio();
    audio.src = URL.createObjectURL(blob);
    audio.play();
  } else if (uri) {
    // Only available on Android and iOS
    await NativeAudio.preload({
      assetId: 'recording',
      assetPath: uri,
      isUrl: true,
    });
    await NativeAudio.play({ assetId: 'recording' });
  }
};
```

Check out the [announcement](https://capawesome.io/blog/announcing-the-capacitor-audio-recorder-plugin/index.md) for more information.

### Bluetooth Low Energy

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) received various bug fixes.

### Contacts

We have published a new [Capacitor Contacts plugin](https://capawesome.io/docs/sdks/capacitor/contacts/index.md). This plugin allows you to create, read, pick, and delete contacts on the device. The plugin is available on Android, iOS and Web.

```
import { 
  Contacts,
  EmailAddressType,
  PhoneNumberType,
  PostalAddressType
} from '@capawesome-team/capacitor-contacts';

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      givenName: 'John',
      familyName: 'Doe',
      emailAddresses: [
        {
          value: 'mail@example.com',
          type: EmailAddressType.Home,
          isPrimary: true
        }
      ],
      phoneNumbers: [
        {
          value: '1234567890',
          type: PhoneNumberType.Mobile,
          isPrimary: true
        }
      ],
      postalAddresses: [
        {
          street: '123 Main St',
          city: 'Springfield',
          state: 'IL',
          postalCode: '62701',
          country: 'USA',
          type: PostalAddressType.Home,
          isPrimary: true
        }
      ]
    }
  });
};
```

Check out the [announcement](https://capawesome.io/blog/announcing-the-capacitor-contacts-plugin/index.md) for more information.

### Nfc

The [Capacitor NFC plugin](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) received various bug fixes.

### PostHog

##### New `getFeatureFlagPayload(...)` method

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) now includes a new `getFeatureFlagPayload(...)` method. This method allows you to get the payload of a feature flag by its key:

```
import { Posthog } from "@capawesome-team/capacitor-posthog";

const getFeatureFlagPayload = async () => {
  const { value } = await Posthog.getFeatureFlagPayload({
    key: "beta_feature",
  });
  return value;
};
```

### Speech Recognition

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) received various bug fixes and improvements.

##### Contextual Strings

You can now provide contextual strings to the `startListening(...)` method. Contextual strings are phrases that should be recognized, even if they are not in the system vocabulary. For this, a new option has been added to the `startListening(...)` method:

```
import { SpeechRecognition } from "@capawesome-team/capacitor-speech-recognition";

const startListening = async () => {
  await SpeechRecognition.startListening({
    contextualStrings: ["Capacitor"],
  });
};
```

##### Background Audio

You can now play background audio while using the Speech Recognition plugin. This allows you to play audio while the speech recognition is listening. For this, three new options have been added to the `startListening(...)` and `stopListening(...)` methods:

```
import { AudioSessionCategory, SpeechRecognition } from "@capawesome-team/capacitor-speech-recognition";

const startListening = async () => {
  await SpeechRecognition.startListening({
    // Set the audio session category to play and record 
    // for recording (input) and playback (output) of audio.
    audioSessionCategory: AudioSessionCategory.PlayAndRecord,
    // Do not deactivate the audio session when the plugin stops listening.
    // Otherwise, the background audio will be stopped as well.
    deactivateAudioSessionOnStop: false,
  });
};

const stopListening = async () => {
  await SpeechRecognition.stopListening({
    // Do not deactivate the audio session when the plugin stops listening.
    // Otherwise, the background audio will be stopped as well.
    deactivateAudioSession: false,
  });
};
```

##### Permission Types

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) now supports different permission types. You can now request the following permissions:

```
import { SpeechRecognition } from "@capawesome-team/capacitor-speech-recognition";

const requestPermissions = async () => {
  const { audioRecording, speechRecognition } =
    await SpeechRecognition.requestPermissions({
      permissions: ["audioRecording", "speechRecognition"],
    });
};
```

The `audioRecording` permission is available on Android and iOS, while the `speechRecognition` permission is only available on iOS.

# Capawesome May 2025 Update

The Capawesome May update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [April 2025 update](https://capawesome.io/blog/2025-april-update/index.md) to catch up on what shipped last month.

## Blog

Check out our latest blog post [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/index.md) to learn how to securely store credentials and authenticate users using the [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) and [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) plugins. It's a cross-platform solution that works on both Android and iOS, and it provides a secure way to store sensitive information such as passwords, tokens, or other credentials.

## CLI

The [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md) has been updated with several new commands and improvements this month.

### New `apps:channels:get` command

The new `apps:channels:get` command allows you to retrieve information about a specific channel in your app. You can use this command to get details such as the channel's ID, name, and metadata. In combination with the `--json` option, you can easily integrate this command into your scripts or workflows to automate tasks related to your app's channels.

For example, the following command retrieves the information about a specific channel in JSON format and extracts the channel ID using [jq](https://github.com/jqlang/jq):

```
npx @capawesome/cli apps:channels:get --app-id my-app-id --channel-id my-channel-id --json | jq ".id"
```

### New `apps:channels:list` command

The new `apps:channels:list` command allows you to list all channels in your app. You can use this command to get an overview of all channels and their metadata. Again, you can use the `--json` option to get the output in JSON format, which makes it easy to integrate into your scripts or workflows. Thanks to the `--limit` and `--offset` options, you can also paginate through the list of channels.

```
npx @capawesome/cli apps:channels:list --app-id my-app-id --limit 10 --offset 0 --json
```

### New `apps:channels:update` command

The new `apps:channels:update` command allows you to update the name or bundle limit of a specific channel in your app.

```
npx @capawesome/cli apps:channels:update --app-id my-app-id --channel-id my-channel-id --name "New Channel Name" --bundle-limit 100
```

## Cloud

### New Logs page

We have introduced a new Logs page in the Capawesome Cloud Console. This page allows you to view and filter logs for your app, making it easier to debug your implementation when getting started. View detailed information on requests and responses, including status and body, to help you identify issues before they become critical. Read more about the new Logs page in the [docs](https://capawesome.io/docs/cloud/live-updates/logs/index.md).

Capawesome Cloud App Logs

## Plugins

### Audio Recorder

The [Capacitor Audio Recorder plugin](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) got several new features and improvements this month.

##### New `bitRate` property

The `StartRecordingOptions` now includes a new `bitRate` property. This property allows you to specify the audio encoding bit rate in bits per second (bps) for the recorded audio. This gives you more control over the audio quality and file size of the recording.

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const startRecording = async () => {
  await AudioRecorder.startRecording({
    bitRate: 128000, // 128 kbps
  });
};
```

##### New `duration` property

The `StopRecordingResult` and `RecordingStoppedEvent` now include a new `duration` property. This property provides the duration of the recorded audio in milliseconds, allowing you to easily access the length of the recording.

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const stopRecording = async () => {
  const { blob, duration, uri } = await AudioRecorder.stopRecording();
  console.log(`Recording duration: ${duration} ms`);
};
```

##### New `sampleRate` property

The `StartRecordingOptions` now includes a new `sampleRate` property. This property allows you to specify the sample rate for the recorded audio. Just like the `bitRate` property, this gives you more control over the audio quality and file size of the recording. The sample rate is specified in Hertz (Hz) and can be set to common values such as 44100 Hz or 48000 Hz.

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const startRecording = async () => {
  await AudioRecorder.startRecording({
    sampleRate: 44100,
  });
};
```

This property is optional and defaults to 44100 if not specified.

##### New `recordingPaused` event

In order to handle audio interruptions, the plugin now emits a new `recordingPaused` event. This event is triggered when the recording is paused, allowing you to handle any necessary actions in your app.

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

AudioRecorder.addListener('recordingPaused', () => {
  console.log('Recording paused');
});
```

### Biometrics

We have published a new [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md). This plugin allows you to use biometric authentication (such as fingerprint or face recognition) in your Capacitor app. The plugin provides a simple API for authenticating users and checking if biometric authentication is available on the device. The plugin is available on Android and iOS.

```
import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';


const authenticate = async () => {
  try {
    await Biometrics.authenticate({
      title: 'Authentication Required',
      subtitle: 'Please authenticate to continue',
      cancelButtonText: 'Cancel',
      iosFallbackButtonText: 'Use Passcode',
    });
  } catch (error) {
    if (error.code === ErrorCode.USER_CANCELED) {
      console.log('User canceled the authentication.');
    } else if (error.code === ErrorCode.NOT_ENROLLED) {
      console.log('No biometric authentication enrolled.');
    } else if (error.code === ErrorCode.NOT_AVAILABLE) {
      console.log('Biometric authentication not available.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};
```

Check out the [announcement post](https://capawesome.io/blog/announcing-the-capacitor-biometrics-plugin/index.md) for more details.

### Contacts

The [Capacitor Contacts plugin](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) has received several new features and improvements this month.

##### New `displayContactById(...)` method

The `displayContactById(...)` method allows you to display a contact in the system's default contacts app. This is useful for apps that need to show contact details without having to implement a custom UI.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const displayContact = async (id: string) => {
  await Contacts.displayContactById({
    id,
  });
};
```

You just need to pass the contact ID of the contact you want to display. The system will then open the default contacts app and show the contact details.

##### New `updateContactById(...)` and `displayUpdateContactById(...)` methods

The `updateContactById(...)` method allows you to update an existing contact by its ID. This is useful for apps that need to modify contact details without having to create a new contact.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const updateContactById = async (id: string) => {
  await Contacts.updateContactById({
    id,
    contact: {
      givenName: 'John',
      familyName: 'Doe'
    }
  });
};
```

It's important to note that all fields are required to be provided when updating a contact, even if you only want to change one field. Fields that are not provided will be removed from the contact. This behavior will be improved in a future release to allow partial updates.

In addition, the `displayUpdateContactById(...)` method allows you to display a contact in the system's default contacts app with the option to update it.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const displayUpdateContact = async (id: string) => {
  await Contacts.displayUpdateContactById({
    id,
  });
};
```

This way, you don't have to implement a custom UI for updating contacts, and you can leverage the system's default contacts app for this purpose.

##### New `countContacts(...)` method

The `countContacts(...)` method allows you to count the number of contacts in the device's contacts database. This allows you to show the number of contacts in your app without having to fetch all contacts.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const countContacts = async () => {
  const { count } = await Contacts.countContacts();
  console.log(`Number of contacts: ${count}`);
};
```

##### Accounts and Groups support

The plugin now supports Android accounts and iOS groups. This allows you to manage contacts that are associated with specific accounts or groups, making it easier to organize and access contacts in your app.

For example, on Android, you can retrieve the accounts associated with the device using the `getAccounts(...)` method:

```
import { Contacts } from "@capawesome-team/capacitor-contacts";

const getAccounts = async () => {
  const { accounts } = await Contacts.getAccounts();
  return accounts;
};
```

You can then create a contact and associate it with an account using the `account` property of the `Contact` object:

```
import { Contacts } from "@capawesome-team/capacitor-contacts";

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      account: {
        name: 'john@doe.tld',
        type: 'com.google'
      },
      givenName: 'John',
      familyName: 'Doe'
    },
  });
};
```

On iOS, you can retrieve the groups associated with the device using the `getGroups(...)` method:

```
import { Contacts } from "@capawesome-team/capacitor-contacts";

const getGroups = async () => {
  const { groups } = await Contacts.getGroups();
  return groups;
};
```

Just like with accounts, you can create a contact and associate it with one (or more) group(s) using the `groupIds` property of the `Contact` object:

```
import { Contacts } from "@capawesome-team/capacitor-contacts";

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      groupIds: ['904DE809-D144-4562-8552-DFEB91F0E4BD:ABGroup'],
      givenName: 'John',
      familyName: 'Doe'
    },
  });
};
```

You can even create a new group using the [`createGroup(...)`](https://capawesome.io/docs/sdks/capacitor/contacts/#creategroup) method:

```
import { Contacts } from "@capawesome-team/capacitor-contacts";

const createGroup = async () => {
  return Contacts.createGroup({
    group: {
      name: 'Friends'
    }
  });
};
```

##### Pagination support

That's not all! The plugin now supports pagination for fetching contacts. This allows you to fetch contacts in smaller chunks, which can improve performance and reduce memory usage, especially when dealing with a large number of contacts.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const getContacts = async () => {
  const { contacts } = await Contacts.getContacts({
    limit: 10, // Fetch 10 contacts at a time
    offset: 0, // Start from the first contact
  });
  console.log(contacts);
};
```

### Secure Preferences

We have published a new [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md). This plugin is a drop-in replacement for the [Capacitor Preferences](https://capacitorjs.com/docs/apis/preferences) plugin and and allows you to securely store key/value pairs such as passwords, tokens or other sensitive information.

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const set = async () => {
  await SecurePreferences.set({
    key: 'password',
    value: '123456',
  });
};

const get = async () => {
  const { value } = await SecurePreferences.get({
    key: 'password',
  });
  console.log(value);
};
```

Check out the [announcement post](https://capawesome.io/blog/announcing-the-capacitor-secure-preferences-plugin/index.md) for more details.

### Wifi

#### New `addNetwork(...)` method

The [Capacitor Wifi plugin](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) now includes a new `addNetwork(...)` method. This method displays a system dialog that allows the user to add a new Wi-Fi network with predefined credentials. This is useful for apps that require the user to connect to a specific Wi-Fi network.

```
import { Wifi } from '@capawesome-team/capacitor-wifi';

const addNetwork = async () => {
  await Wifi.addNetwork({
    ssid: 'MyNetwork',
    password: 'MyPassword',
  });
}
```

Here is a short video demonstrating how this looks like in practice on Android:

\[

\](/docs/assets/videos/posts/20250601_plugins_wifi_addnetwork.mp4)

# Capawesome November 2025 Update

The Capawesome November update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [October 2025 update](https://capawesome.io/blog/2025-october-update/index.md) to catch up on what shipped last month.

## Cloud

### Native Builds

We are excited to announce the launch of Native Builds for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md), a production-ready cloud platform for compiling iOS and Android applications. This service eliminates the need for developers to maintain local CI/CD infrastructure or complex build configurations.

Native Builds provides pre-optimized environments with current Node.js, Java, and Xcode versions running on macOS 15 with M4 instances. You can connect your GitHub, GitLab, Bitbucket, or Azure DevOps repositories and trigger builds manually or automatically. The platform executes builds 3-5x faster compared to traditional CI/CD platforms like GitHub Actions.

The service connects directly to TestFlight, the App Store, and Google Play Store, allowing one-click submissions following successful builds. You can also use the CLI to trigger builds from any operating system—Windows, Linux, or macOS—without requiring Xcode or Android Studio installation locally.

Check out our [announcement post](https://capawesome.io/blog/announcing-capawesome-cloud-native-builds/index.md) to learn more about Native Builds and how to get started.

## Plugins

### Age Signals

The [Capacitor Age Signals plugin](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) has been updated to version 0.1.1 and now includes support for iOS using the official `DeclaredAgeRange` API. This allows developers to access age-related signals on iOS devices, enabling age-appropriate content delivery and compliance with age-related regulations.

### Audio Player

The [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) has received several bug fixes and improvements. Notably, we have added a new `stop` event that is emitted when audio playback stops. Additionally, we fixed an issue on Android where audio would continue playing even after the app was destroyed, and improved audio focus handling on Android to ensure proper playback behavior.

### Datetime Picker

The [Capacitor Datetime Picker plugin](https://capawesome.io/docs/sdks/capacitor/datetime-picker/index.md) now includes a new [`cancel()`](https://capawesome.io/docs/sdks/capacitor/datetime-picker/#cancel) method that dismisses an active datetime picker dialog. This is useful when you need to programmatically close the picker without waiting for user interaction, such as when implementing timeout logic or conditional cancellation based on app state changes.

```
import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';
import { App } from '@capacitor/app';

App.addListener('appStateChange', ({ isActive }) => {
  if (!isActive) {
    DatetimePicker.cancel();
  }
});
```

If there is no active picker, this method does nothing. This method is available on Android and iOS.

### Firebase

#### Authentication

The [Capacitor Firebase Authentication plugin](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/index.md) now includes a new [`getIdTokenResult(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/#getidtokenresult) method that retrieves a deserialized JSON Web Token (JWT) containing user identification data. This provides detailed token information beyond just the token string, including authentication time, expiration time, sign-in provider, and custom claims.

```
import { FirebaseAuthentication } from '@capawesome-team/capacitor-firebase-authentication';

const getTokenDetails = async () => {
  const currentUser = await FirebaseAuthentication.getCurrentUser();
  if (!currentUser) {
    return;
  }

  const result = await FirebaseAuthentication.getIdTokenResult({
    forceRefresh: true
  });

  console.log('Token claims:', result.claims);
  console.log('Expires:', new Date(result.expirationTime));
};
```

This is particularly useful when you need to inspect token claims or verify authentication details programmatically.

### Media Session

The [Capacitor Media Session plugin](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) has received a bug fix that ensures the media session is properly stopped when the app is closed on Android. This prevents media controls from remaining active after the app has been destroyed.

### ML Kit

#### Barcode Scanning

The [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) plugin now supports an `autoZoom` option for the [`scan(...)`](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/#scan) method on Android. When enabled, this feature automatically adjusts the camera's zoom to optimize barcode detection, enhancing the scanning experience by dynamically focusing on barcodes at various distances.

```
import { BarcodeScanner, BarcodeFormat } from '@capawesome-team/capacitor-mlkit-barcode-scanning';

const scan = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    formats: [BarcodeFormat.QrCode],
    autoZoom: true,
  });
  return barcodes;
};
```

This option is available on Android.

### Posthog

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) now supports session replay functionality, allowing you to record and playback user interactions within your Capacitor app. This feature captures visual snapshots of user sessions, enabling you to understand user behavior and troubleshoot issues.

You can enable session replay by setting `enableSessionReplay: true` in your configuration:

```
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Posthog: {
      apiKey: 'your_key',
      enableSessionReplay: true,
      sessionReplayConfig: {
        screenshotMode: false,
        maskAllTextInputs: true,
        captureNetworkTelemetry: true
      }
    }
  }
};
```

The plugin provides granular control over what data is captured, including options to mask text inputs and images, enable network telemetry, and control the snapshot interval. Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) to learn more about session replay configuration options.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) now supports Android, bringing in-app purchase functionality to both Android and iOS platforms. This plugin provides a simple API for managing purchases, subscriptions, and product information across mobile platforms.

### Screen Orientation

The [Capacitor Screen Orientation plugin](https://capawesome.io/docs/sdks/capacitor/screen-orientation/index.md) has been updated to make the `LockOptions` parameter optional for the [`lock(...)`](https://capawesome.io/docs/sdks/capacitor/screen-orientation/#lock) method. If no options are provided, the method now locks the screen orientation to the current orientation by default.

```
import { ScreenOrientation } from '@capawesome-team/capacitor-screen-orientation';

const lock = async () => {
  await ScreenOrientation.lock();
};
```

This makes it easier to quickly lock the screen to its current orientation without needing to specify the orientation type explicitly.

# Capawesome October 2025 Update

The Capawesome October update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [September 2025 update](https://capawesome.io/blog/2025-september-update/index.md) to catch up on what shipped last month.

## Cloud

### Equivalent Version Codes for Live Updates

We have added support for Equivalent Version Codes in [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md), giving you more control over when live updates are delivered to your users. This new parameter works alongside minimum and maximum version code constraints to create precise compatibility rules.

The Equivalent parameter functions as a skip condition: if a user's native app already has the exact version code you've marked as equivalent, the live update won't be downloaded. This prevents redundant downloads when the user's app already matches the bundle version.

For example, when creating a bundle using the CLI:

```
npx @capawesome/cli apps:bundles:create --android-eq 11
```

If a user's Android app is at version code 11, they won't receive this bundle since they already have the equivalent version. This feature helps reduce unnecessary data transfer and ensures users only download updates when needed.

Check out our [documentation on versioned bundles](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/#versioned-bundles) to learn more about restricting live updates to specific native versions.

## Plugins

### Age Signals

We have published a new [Capacitor Age Signals plugin](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) that allows you to request user age signals from Google Play on Android. This plugin enables developers to access Google's Play Age Signals API to retrieve age-related information about users within their applications.

The plugin provides key capabilities including age verification status, age range data for supervised accounts, and parental approval tracking. Here's a simple example of how to use the plugin:

```
import { AgeSignals } from '@capawesome-team/capacitor-age-signals';

const checkAgeSignals = async () => {
  const result = await AgeSignals.checkAgeSignals();
  console.log('User Status:', result.userStatus);
  console.log('Age Lower:', result.ageLower);
  console.log('Age Upper:', result.ageUpper);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) to learn more about the plugin and its features.

### App Update

The [Capacitor App Update plugin](https://capawesome.io/docs/sdks/capacitor/app-update/index.md) now supports an `androidPackageName` option for the [`openAppStore(...)`](https://capawesome.io/docs/sdks/capacitor/app-update/#openappstore) method. This parameter allows you to specify which app to open in the Google Play Store, making it easy to direct users to a different application if needed.

```
import { AppUpdate } from '@capawesome-team/capacitor-app-update';

const openAppStore = async () => {
  await AppUpdate.openAppStore({
    androidPackageName: 'com.example.app'
  });
};
```

If you omit this parameter, the plugin defaults to opening the current app's Play Store listing.

### Audio Player

The [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) now supports web asset paths, providing a streamlined approach for playing bundled audio resources. The new `src` parameter represents the path to the web asset file to play and works across all platforms.

On Android, the plugin is limited to web assets only, while iOS and Web support both web assets and remote URLs. If you provide multiple audio sources, the plugin follows a clear priority: `blob` takes precedence over `src`, and `uri` takes priority over `src`.

### Bluetooth Low Energy

##### New `autoReconnect` option

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) now supports an `autoReconnect` option when establishing device connections. This feature enables automatic reconnection to peripherals when the connection is lost, improving reliability for background operations.

The option is available on both Android and iOS (17.0+) and defaults to `false`. Here's how to use it with the [`connect(...)`](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#connect) method:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.connect({
  deviceId: '00:00:00:00:00:00',
  autoReconnect: true
});
```

##### New `isLocationEnabled()` method

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) now includes a new [`isLocationEnabled()`](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#islocationenabled) method that checks whether location services are active on the device. This is particularly useful on Android, where location services are often required for BLE scanning operations to function properly.

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const result = await BluetoothLowEnergy.isLocationEnabled();
console.log(result.enabled);
```

This method is available on Android only.

### Datetime Picker

The [Capacitor Datetime Picker plugin](https://capawesome.io/docs/sdks/capacitor/datetime-picker/index.md) now supports a `minuteInterval` option for the [`present(...)`](https://capawesome.io/docs/sdks/capacitor/datetime-picker/#present) method. This parameter controls the granularity of the minute selector, allowing you to set incremental steps for minute selection rather than requiring users to pick every single minute.

For example, setting it to 15 means users can only select times at 0, 15, 30, or 45 minutes past the hour:

```
import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const present = async () => {
  const { value } = await DatetimePicker.present({
    mode: 'time',
    minuteInterval: 15,
    theme: 'dark',
    locale: 'en-US',
  });

  return value;
};
```

The value must be evenly divisible into 60 and defaults to 1 (every minute). This option is only available on iOS for time and datetime modes.

### Geocoder

We have published a new [Capacitor Geocoder plugin](https://capawesome.io/docs/sdks/capacitor/geocoder/index.md) that enables bidirectional location conversion on Android, iOS, and Web. The plugin translates addresses into geographic coordinates and converts coordinates back into human-readable addresses.

The plugin integrates with native APIs on mobile platforms for accuracy and reliability, and supports multiple geocoding providers (Google Maps and OpenStreetMap) on web. Here are simple examples of both geocoding and reverse geocoding:

```
import { Geocoder } from '@capawesome-team/capacitor-geocoder';

const geocode = async () => {
  const result = await Geocoder.geocode({
    address: '1600 Amphitheatre Parkway, Mountain View, CA',
  });
};

const geodecode = async () => {
  const result = await Geocoder.geodecode({
    latitude: 37.422,
    longitude: -122.084,
  });
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/geocoder/index.md) to learn more about the plugin and its features.

### Media Session

We have published a new [Capacitor Media Session plugin](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) that enables you to manage media playback controls across Android, iOS, and Web platforms. The plugin facilitates interaction with hardware media keys, lock screen controls, and notification-based media management.

Here's a basic example of how to use the plugin:

```
import { MediaSession, MediaSessionAction } from '@capawesome-team/capacitor-media-session';

const setupMediaSession = async () => {
  await MediaSession.setMetadata({
    title: 'Song Name',
    artist: 'Artist Name',
    album: 'Album Name',
  });

  await MediaSession.registerActionHandler({
    action: MediaSessionAction.Play
  });

  MediaSession.addListener('action', async (event) => {
    if (event.action === MediaSessionAction.Play) {
      // Handle play action
    }
  });
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) to learn more about the plugin and its features.

### Wifi

The [Capacitor Wifi plugin](https://capawesome.io/docs/sdks/capacitor/wifi/index.md) now allows connection to networks without internet access on Android. This fix ensures that you can connect to local Wi-Fi networks that don't have internet connectivity, which is particularly useful for IoT devices and local network applications.

# Capawesome September 2025 Update

The Capawesome September update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [August 2025 update](https://capawesome.io/blog/2025-august-update/index.md) to catch up on what shipped last month.

## Capver

We have published a new CLI called [Capver](https://github.com/capawesome-team/capver) for managing versions in a Capacitor project across multiple platforms. The CLI helps you set, increment, and synchronize versions in your `package.json`, `capacitor.config.json`, `Info.plist` (iOS), and `build.gradle` (Android) files. This ensures that all platforms use the same version number, making it easier to manage and release your app.

First, install the CLI using npm:

```
npm install -g @capawesome/capver
```

After installing, you can use the following commands to manage your app versions:

```
# Initialize a new Capacitor project with version 0.0.1
npx @capawesome/capver set 0.0.1

# Increment the patch version
npx @capawesome/capver patch

# Increment the minor version
npx @capawesome/capver minor

# Increment the major version
npx @capawesome/capver major

# Increment only the build number
npx @capawesome/capver hotfix

# Check version consistency across platforms
npx @capawesome/capver get

# Synchronize all platforms to use the highest version found
npx @capawesome/capver sync
```

Check out the [documentation](https://github.com/capawesome-team/capver) to learn more about the CLI and its features.

## Cloud

### Audit Logs

You can now view audit logs for your Capawesome Cloud organizations. Audit logs provide a detailed record of actions taken within your organization, including deployments, configuration changes, and user activities. This feature helps you monitor and track changes to your organization for security and compliance purposes. Read more about in our [documentation](https://capawesome.io/docs/cloud/organizations/audit-logs/index.md).

## Newsletter

After a long break, we have finally sent out a new [Capawesome Newsletter](/newsletter/) with some cool updates in offers exclusively for our newsletter subscribers. If you haven't subscribed yet, make sure to [sign up](/newsletter/) to stay updated with the latest news and updates from Capawesome.

## Plugins

### Audio Player

We have published a new [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) that allows you to play audio files on Android, iOS and Web. Here's a simple example of how to use the plugin to play an audio file:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
import { Capacitor } from '@capacitor/core';
import { Filesystem } from '@capacitor/filesystem';

const play = async () => {
  if (Capacitor.getPlatform() === 'web') {
    const assetUrl = 'https://www.example.com/audio.mp3';
    const response = await fetch(assetUrl);
    const blob = await response.blob();
    await AudioPlayer.play({ blob, loop: false, volume: 100, position: 0 });
  } else {
  const { uri } = await Filesystem.getUri({
    directory: FilesystemDirectory.Documents,
    path: 'audio.mp3',
  });
    await AudioPlayer.play({ uri, loop: false, volume: 100, position: 0 });
  }
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) to learn more about the plugin and its features.

### Bluetooth Low Energy

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) received multiple improvements this month.

##### Auto Initialization

The plugin now automatically initializes itself on the first call to any of its methods. This makes it easier to use the plugin, as you no longer need to call the `initialize()` method manually.

##### Manufacturer Data

You can now include manufacturer-specific data when advertising as a peripheral. This allows you to provide additional information about your device that can be used by other Bluetooth devices. Here's an example of how to start advertising with manufacturer data:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startAdvertising = async () => {
  await BluetoothLowEnergy.startAdvertising({
    manufacturerData: {
      0xffff: [1, 2, 3]
    },
    name: 'MyDevice',
    services: []
  });
};
```

### Contacts

The [Capacitor Contacts plugin](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) now includes a new `openSettings()` method that opens the device's settings page for the app. This is useful for prompting users to grant permissions if they have previously denied access to contacts.

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const openContactsSettings = async () => {
  await Contacts.openSettings();
};
```

### Live Update

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) has received small bug fixes. Please check out the [CHANGELOG.md](https://capawesome.io/docs/sdks/capacitor/live-update/#changelog) for more details.

### Speech Recognition

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) now supports a `taskHint` option for the `startListening()` method on iOS. This option allows you to specify the type of speech recognition task you are performing, which can help improve accuracy and performance.

```
import { SpeechRecognition, TaskHint } from '@capawesome-team/capacitor-speech-recognition';

const startListening = async () => {
  await SpeechRecognition.startListening({
    taskHint: TaskHint.Dictation
  });
};
```

Check out the `TaskHint` enum in the [documentation](https://capawesome.io/docs/sdks/capacitor/speech-recognition/#taskhint) for all available options.

### Speech Synthesis

The [Capacitor Speech Synthesis plugin](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/index.md) now automatically initializes itself on the first call to any of its methods. This makes it easier to use the plugin, as you no longer need to call the `initialize()` method manually.

### Share Target

The [Capacitor Share Target plugin](https://capawesome.io/docs/sdks/capacitor/share-target/index.md) now provides the `mimeType` and `name` properties for shared files. This allows you to get more information about the files that are shared with your app.

```
import { Capacitor } from '@capacitor/core';
import { ShareTarget } from '@capawesome-team/capacitor-share-target';

const addListener = async () => {
  await ShareTarget.addListener('shareReceived', (event) => {
    const firstFile = event.files[0];
    console.log('File URI: ', firstFile.uri);
    console.log('File MIME type:', firstFile.mimeType);
    console.log('File name:', firstFile.name);
  });
};
```

# Capawesome April 2026 Update

The Capawesome April update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Blog

We published several new articles this month. Here are the highlights:

- [Live Updates vs `server.url`: The Right Way to Update Your Capacitor App Remotely](https://capawesome.io/blog/the-right-way-to-update-your-capacitor-app-remotely/index.md) — Many teams reach for `server.url` to ship updates without an app store review, but the option was never designed for production. We compare both approaches across offline support, performance, security, and app store compliance.
- [How to Build and Deploy iOS Apps Without Owning a Mac](https://capawesome.io/blog/how-to-build-and-deploy-ios-apps-without-a-mac/index.md) — Apple's iOS toolchain only runs on macOS, but that doesn't mean you need to buy a Mac to ship Capacitor apps. We walk through three ways to get past the macOS requirement and show how to trigger signed iOS builds from Windows or Linux.
- [Apple Now Requires Xcode 26 for App Store Submissions](https://capawesome.io/blog/xcode-26-requirement-for-capacitor-apps/index.md) — As of April 28, every iOS submission to App Store Connect must be built with Xcode 26 and the iOS 26 SDK. We break down what this means for Capacitor apps and how Capawesome Cloud customers are already covered by default.

## Cloud

### Faster API Response Times

We rolled out major backend infrastructure improvements that reduce Capawesome Cloud API response times by up to 5x for all customers. This means faster update checks via the [Live Update SDK](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) and a more responsive experience when navigating the [Cloud Console](https://console.cloud.capawesome.io). No action needed on your end — every app and organization benefits automatically.

### Android Keystore Generator

We launched the [Android Keystore Generator](https://capawesome.io/tools/android-keystore-generator/) — a free, browser-based tool for creating PKCS#12 keystores (`.p12` files) for signing your Android apps. It produces RSA 2048-bit keys with SHA-256 signing that meet all Google Play requirements, and your private key never leaves your device thanks to the Web Crypto API. No `keytool`, no command-line flags, no local tooling required. This is especially useful when you're setting up CI/CD pipelines and need a keystore quickly.

### iOS Certificate Generator

We also launched the [iOS Certificate Generator](https://capawesome.io/tools/ios-certificate-generator/) — a free, browser-based tool that simplifies one of the most frustrating parts of iOS development. You can create a Certificate Signing Request (CSR), upload it to the Apple Developer Portal, and convert Apple's `.cer` file into a ready-to-use `.p12` bundle, all without macOS or Keychain Access. Just like the keystore generator, your private key stays on your device.

### SSO Domain Verification

[Single Sign-On](https://capawesome.io/docs/cloud/organizations/sso/index.md) now includes a domain verification step. Before members can sign in via SSO, you must verify ownership of your email domain by adding a TXT record to your DNS configuration. This prevents unauthorized SSO provider registration and ensures only domain owners can enable SSO for their domain. Once verified, new users matching the verified domain are provisioned automatically when they sign in through your Identity Provider — no invitation required.

With this safeguard in place, SSO is no longer locked behind the Enterprise plan — it's now available on the **Business plan** as well, so smaller teams can adopt SSO without an enterprise contract.

### Viewer Role

A new [Viewer role](https://capawesome.io/docs/cloud/organizations/memberships/#roles-and-permissions) is now available for organization members. Viewers can see apps and app resources but cannot make changes, which is ideal for stakeholders, auditors, or QA team members who only need read-only access. You can assign the role when inviting new members or change it for existing members in the organization settings.

### Improved Webhook Message Layout

We significantly improved the message layout for [outgoing webhooks](https://capawesome.io/docs/cloud/webhooks/index.md) when using the [Discord](https://capawesome.io/docs/cloud/integrations/discord/index.md), [Slack](https://capawesome.io/docs/cloud/integrations/slack/index.md), or [Microsoft Teams](https://capawesome.io/docs/cloud/integrations/microsoft-teams/index.md) format. Notifications now include the build number, platform, status, branch, commit hash, commit message, and duration in a clean, scannable layout — so your team can see what shipped at a glance:

```
:white_check_mark: Build #2 (Android) succeeded for Demo App

Branch: main
Commit: 8d7da2d — chore: update .gitignore
Duration: 1m 17s
```

Combined with [Automations](https://capawesome.io/docs/cloud/automations/index.md), this makes it easy to keep your team informed in chat as soon as a build finishes or a deployment goes out.

### Capawesome CLI 4.7.0

We released [Capawesome CLI 4.7.0](https://capawesome.io/blog/capawesome-cli-4-7-0-release/index.md) with a new `apps:liveupdates:create` command that builds and deploys live updates in one step using Cloud Runners, plus app linking, app transfer, ad hoc environment variables, and source map detection. Check out the [release blog post](https://capawesome.io/blog/capawesome-cli-4-7-0-release/index.md) for the full breakdown.

## Plugins

### Android Edge-to-Edge Support

The [Capacitor Android Edge-to-Edge Support plugin](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) received several reliability fixes. Edge-to-edge is now detected at runtime instead of inferred from the API level, the top margin is only applied on Android 15+, and the bottom margin no longer double-counts when the keyboard is visible. If you rely on this plugin to handle system bars on modern Android, we recommend upgrading to the latest version.

### Audio Recorder

The [Capacitor Audio Recorder plugin](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) adds a new `uri` option to the `startRecording(...)` method. You can now specify exactly where the recorded audio file should be saved instead of relying on the temporary cache location:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { Filesystem, Directory } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'recording.m4a',
});

await AudioRecorder.startRecording({ uri });
```

If you don't pass a `uri`, recordings still land in the cache directory as before. This option is available on Android and iOS.

### OAuth

The [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) received several improvements to the `login(...)` method. A new `uiLocales` option lets you request a specific UI language from the Identity Provider, and `prompt` and `loginHint` are now correctly forwarded to the authorization request on iOS:

```
import { OAuth } from '@capawesome-team/capacitor-oauth';

const result = await OAuth.login({
  configuration: { /* ... */ },
  uiLocales: ['de', 'en'],
  prompt: 'login',
  loginHint: 'user@example.com',
});
```

This release also fixes a bug where the AppAuth session was not resumed when the app was reopened via a URL on iOS.

### Speech Recognition

The [Capacitor Speech Recognition plugin](https://capawesome.io/docs/sdks/capacitor/speech-recognition/index.md) now supports full on-device speech recognition. Audio stays on the device, which means better privacy and offline support for voice-driven apps:

```
import { SpeechRecognition } from '@capawesome-team/capacitor-speech-recognition';

await SpeechRecognition.startListening({
  language: 'en-US',
  requireOnDeviceRecognition: true,
});
```

Three new APIs power this:

- `getOnDeviceLanguages()` — query installed and downloadable on-device languages. Available on Android 33+ and iOS 26+.
- `downloadOnDeviceLanguage()` — trigger an on-device language model download on demand. Available on Android 34+ and iOS 26+.
- `requireOnDeviceRecognition` option on `startListening(...)` — force recognition to run fully on-device, never falling back to the cloud. Available on Android 33+ and iOS 13+.

This is a great fit for healthcare apps, journaling tools, or any voice-driven interface in low-connectivity environments — anywhere privacy or reliability matters.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

April was mostly a Cloud-focused month for us, with only a handful of plugin updates landing on the open source side. On the Cloud side, faster API responses, free browser-based signing tools, and SSO domain verification make it easier and safer to ship Capacitor apps at any scale. On the Plugins side, on-device speech recognition and the new `uri` option for audio recordings still unlock entirely new use cases for voice-driven and media apps. If you missed last month's news, catch up with the [March 2026 update](https://capawesome.io/blog/2026-march-update/index.md).

And we're not slowing down — we have something big in the works for May that we can't wait to share. Stay tuned.

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to stay updated on the latest news and updates.

# Capawesome February 2026 Update

The Capawesome February update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Cloud

### Automations

We are excited to introduce Automations for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md)! Automations let you trigger builds automatically from Git events — no external CI/CD required. You can configure branch push and tag creation triggers with pattern matching, filter by commit messages, and define full build settings per automation.

\[

\](/docs/assets/videos/posts/announcing-capawesome-cloud-automations/05f0e923-8ac3-4297-bb60-f4ad403851bf.mp4)

When an automation is created, a webhook is automatically registered in your connected Git repository. You can also enable skip CI functionality by including keywords like `[skip ci]` in your commit messages. Check out the [announcement post](https://capawesome.io/blog/announcing-capawesome-cloud-automations/index.md) and the [Automations documentation](https://capawesome.io/docs/cloud/automations/index.md) for more details.

### Webhooks

Capawesome Cloud now supports outgoing webhooks, allowing you to receive real-time HTTP notifications for key events like builds, deployments, and jobs. Each webhook payload is signed using HMAC-SHA256 so you can verify authenticity, and a full delivery history is available in the Console for troubleshooting.

On top of that, we added native notification support for Discord, Slack, and Microsoft Teams. When you register a webhook URL from one of these platforms, Capawesome Cloud automatically detects the platform and formats the notification accordingly. Check out the [Webhooks documentation](https://capawesome.io/docs/cloud/webhooks/index.md) to learn more.

### Channel Discovery

Channel discovery allows the [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) to fetch the list of available channels without requiring authentication. This is useful for apps that want to let developers or QA select a channel from a list, for example to switch to a beta channel.

To enable channel discovery, navigate to the [Settings](https://console.cloud.capawesome.io/apps/_/settings) page in the Capawesome Cloud Console and enable the "Channel Discovery" toggle in the "Live Update Channels" section. Once enabled, you can use the [`fetchChannels(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#fetchchannels) method of the Live Update plugin to retrieve the available channels. Check out the [Channels documentation](https://capawesome.io/docs/cloud/live-updates/channels/#channel-discovery) to learn more.

### Build Artifact Deletion

You can now delete build artifacts directly from the Capawesome Cloud Console. This gives you more control over storage usage and makes it easier to clean up old or unnecessary build outputs.

### Polar

We have migrated our billing infrastructure to [Polar](https://polar.sh/). This change improves the checkout experience and provides a more streamlined subscription management process. Existing subscriptions through our previous payment provider Lemon Squeezy continue to work as before. If you experience any payment issues, please reach out to our support team so we can assist with the migration.

## Plugins

### Android Gradle Plugin 9 Compatibility

All Capawesome plugins have been updated to support Android Gradle Plugin (AGP) 9.0. AGP 9 removed support for the legacy `proguard-android.txt` default ProGuard file, which caused build failures in projects using the latest Android tooling. All plugins now use the updated `proguard-android-optimize.txt` configuration, ensuring compatibility with AGP 9 out of the box.

If you're upgrading to AGP 9, make sure to update all Capawesome plugins to their latest versions. Check out our [blog post](https://capawesome.io/blog/how-to-fix-capacitor-plugin-build-errors-with-agp-9/index.md) for more details on the issue and workarounds.

### Google Sign-In

We are excited to announce the initial release of the [Capacitor Google Sign-In plugin](https://capawesome.io/docs/sdks/capacitor/google-sign-in/index.md)! This plugin lets you add Google Sign-In to your Capacitor app on Android, iOS, and Web with a single, lightweight integration.

The plugin supports authentication with ID tokens, authorization with OAuth scopes, and user profile retrieval. It returns comprehensive user data including email, display name, profile picture, and access tokens:

```
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const signIn = async () => {
  const result = await GoogleSignIn.signIn();
  console.log('Email:', result.email);
  console.log('Display Name:', result.displayName);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/google-sign-in/index.md) to learn more about getting started with the Google Sign-In plugin.

### OAuth

We are excited to announce the initial release of the [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md)! This plugin provides a complete OAuth 2.0 and OpenID Connect implementation for Capacitor with support for PKCE, auto-discovery, and token refresh on Android, iOS, and Web.

The plugin includes methods for login, logout, token refresh, and ID token decoding:

```
import { OAuth } from '@capawesome-team/capacitor-oauth';

const login = async () => {
  const result = await OAuth.login({
    authorizationEndpoint: 'https://example.com/authorize',
    tokenEndpoint: 'https://example.com/token',
    clientId: 'your-client-id',
    redirectUrl: 'your-redirect-url',
    scope: 'openid profile email',
  });
  console.log('Access Token:', result.accessToken);
};
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) to learn more about getting started with the OAuth plugin.

### SQLite

The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) has received several notable updates this month.

#### Key-Value Store

A new `SqliteKeyValueStore` class provides a simple key-value API on top of SQLite, making it easy to store and retrieve data without writing SQL:

```
import { Sqlite, SqliteKeyValueStore } from '@capawesome-team/capacitor-sqlite';

const store = new SqliteKeyValueStore(Sqlite);

await store.set({ key: 'username', value: 'robin' });
const result = await store.get({ key: 'username' });
console.log('Value:', result.value);
```

#### Electron Support

The plugin now supports Electron using Node.js's native `node:sqlite` module, which requires Node.js 22.5.0+ and Electron 33+. Databases are stored in the `userData` directory on each platform. Note that encryption features are not supported on Electron.

#### Bundled SQLite Engine

A new opt-in option lets you bundle the [requery/sqlite-android](https://github.com/nicholasgasior/sqlite-android) library on Android, giving you control over the SQLite version used by your app instead of relying on the device's built-in version.

### PostHog

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) now includes a new [`getDistinctId()`](https://capawesome.io/docs/sdks/capacitor/posthog/#getdistinctid) method that returns the distinct ID of the current user. This is useful when you need to correlate PostHog events with your own backend or identify the current user in support workflows:

```
import { Posthog } from '@capawesome/capacitor-posthog';

const getDistinctId = async () => {
  const result = await Posthog.getDistinctId();
  console.log('Distinct ID:', result.distinctId);
};
```

This method is available on Android, iOS, and Web.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) now supports `basePlanId` and `offerId` options in the [`purchaseProduct(...)`](https://capawesome.io/docs/sdks/capacitor/purchases/#purchaseproduct) method on Android. This allows you to specify which base plan and offer to use when purchasing a subscription, giving you more control over Google Play subscription pricing:

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const purchase = async () => {
  await Purchases.purchaseProduct({
    productId: 'com.example.premium',
    basePlanId: 'monthly',
    offerId: 'intro-offer',
  });
};
```

These options are available on Android.

### Firebase

#### Cloud Functions

The [Capacitor Firebase Cloud Functions plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/index.md) now supports a `timeout` option when calling functions, allowing you to configure how long the client waits before timing out. Additionally, the `regionOrCustomDomain` option is now properly supported on Android, ensuring consistent behavior across platforms.

### LibSQL

The [Capacitor LibSQL plugin](https://capawesome.io/docs/sdks/capacitor/libsql/index.md) now supports the [`sync(...)`](https://capawesome.io/docs/sdks/capacitor/libsql/#sync) method on Android, enabling you to synchronize your local embedded replica with the remote database:

```
import { Libsql } from '@capawesome/capacitor-libsql';

const sync = async () => {
  await Libsql.sync({
    connectionId: 'my-connection',
  });
};
```

This method was previously only available on iOS and is now supported on both Android and iOS.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

This was a packed month for Capawesome. On the Cloud side, Automations and Webhooks bring powerful CI/CD and notification capabilities, while several new plugins — including Google Sign-In, OAuth, and major SQLite enhancements — expand what you can build with Capacitor. If you missed last month's news, catch up with the [January 2026 update](https://capawesome.io/blog/2026-january-update/index.md).

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](/newsletter/) to stay updated on the latest news and updates.

# Capawesome January 2026 Update

The Capawesome January update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

In case you missed it, check out the [December 2025 update](https://capawesome.io/blog/2025-december-update/index.md) to catch up on what shipped last month.

## Cloud

### App Store Connect API Key

You can now authenticate with App Store Connect using an API Key when configuring an Apple App Store destination in [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). Previously, authentication was only available via Apple ID and app-specific password. The new API Key method lets you upload a `.p8` private key file along with the Key ID and Issuer ID from App Store Connect, providing a more robust and streamlined way to submit your iOS builds to TestFlight.

To get started, navigate to the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations) page in the Capawesome Cloud Console and select `API Key` as the authentication method. Check out the [Apple App Store documentation](https://capawesome.io/docs/cloud/app-store-publishing/destinations/apple-app-store/#api-key) for instructions on obtaining the required credentials.

### Play Store Release Status

When configuring a Google Play Store destination, you can now choose the release status for your app submissions. Two options are available:

- **Draft**: For initial releases that require manual review before publishing. This is useful for the very first release on a track where additional setup may be needed in Google Play Console.
- **Completed**: For releases that should be automatically published to the selected track, which is the typical choice for subsequent releases.

Check out the [Google Play Store documentation](https://capawesome.io/docs/cloud/app-store-publishing/destinations/google-play-store/#release-status) to learn more.

### Protected Channels

Channels can now be marked as "protected" to enhance the security of your live updates. When a channel is protected, all builds associated with that channel must be code-signed before they can be distributed to users. This ensures that only authorized builds are delivered through the protected channel. Check out the [Protected Channels documentation](https://capawesome.io/docs/cloud/live-updates/channels/#protected-channels) to learn more.

### Pause and Resume Channels

You can now pause and resume live update channels directly from the [Capawesome Cloud Console](https://console.cloud.capawesome.io/apps/_/channels) or via the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md). When a channel is paused, devices stop receiving new live updates from that channel until you resume it. This is useful for temporary holds during maintenance windows, controlling production deployments while testing new bundles, or quickly halting problematic updates without deleting the channel. Check out the [blog post](https://capawesome.io/blog/capawesome-cloud-channel-pausing/index.md) for more details.

### Enforce 2FA for Organization Members

Organizations can now enforce two-factor authentication (2FA) for all members. When 2FA enforcement is enabled, new members must have 2FA enabled on their account before they can join the organization. Members who are already part of the organization retain access, but they cannot disable 2FA while they remain a member. This gives organizations better control over account security across their teams. Check out the [Two-Factor Authentication documentation](https://capawesome.io/docs/cloud/organizations/two-factor-authentication/index.md) to learn more.

## Plugins

### Android Edge-to-Edge Support

The [Capacitor Android Edge-to-Edge Support plugin](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/index.md) has received important bug fixes and improvements. The plugin manages edge-to-edge display support on Android by applying proper insets to the webview, preventing Android's edge-to-edge changes from affecting apps that haven't been designed to support it. If you're targeting recent Android versions, make sure to update to the latest version of the plugin.

### Audio Player

The [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) now supports adjustable playback rate with pitch preservation. You can control the playback speed using the [`setRate(...)`](https://capawesome.io/docs/sdks/capacitor/audio-player/#setrate) method, with values between 0.5 and 2.0 recommended for consistent behavior across devices:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const setPlaybackRate = async () => {
  await AudioPlayer.setRate({ rate: 1.5 });
};
```

This feature is available on Android (SDK 23+), iOS, and Web.

### Biometrics

The [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) now includes a new [`getBiometricType()`](https://capawesome.io/docs/sdks/capacitor/biometrics/#getbiometrictype) method that returns the type of biometric authentication available on the device. If multiple biometric types are available, the method prioritizes them in the order Face > Iris > Fingerprint:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const getBiometricType = async () => {
  const result = await Biometrics.getBiometricType();
  console.log('Biometric type:', result.type);
};
```

This method is available on Android and iOS.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) has received several new features this month.

A new `productCategory` property is now available on Android to filter product queries. You can specify either `ProductCategory.InApp` for consumables and non-consumables or `ProductCategory.Subscription` for subscription products, giving you more control over which products are returned.

The new [`getProductsByIds(...)`](https://capawesome.io/docs/sdks/capacitor/purchases/#getproductsbyids) method allows you to retrieve details for multiple products in a single call:

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const getProducts = async () => {
  const result = await Purchases.getProductsByIds({
    productIds: ['com.example.premium', 'com.example.pro']
  });

  for (const product of result.products) {
    console.log('Product:', product.displayName);
    console.log('Price:', product.price);
  }
};
```

Transactions now include platform-specific verification data for server-side IAP validation. On iOS, transactions provide a JWS (JSON Web Signature) representation, while on Android they include the purchase token, original JSON data, and RSA signature.

A new [`isIntroOfferAvailableForProduct(...)`](https://capawesome.io/docs/sdks/capacitor/purchases/#isintroofferavailableforproduct) method has been added to check whether a user is eligible for introductory offers on subscriptions. This leverages StoreKit 2's eligibility checks on iOS and examines available pricing phases on Android.

### Square Mobile Payments

We are excited to announce the initial release of the [Capacitor Square Mobile Payments plugin](https://capawesome.io/docs/sdks/capacitor/square-mobile-payments/index.md)! This unofficial Capacitor plugin integrates Square's Mobile Payments SDK, enabling you to accept in-person card payments through Square readers in your Android and iOS applications.

The plugin supports multiple card entry methods including contactless (tap), chip insertion, swipe, and manual keying. It also includes reader management for pairing and monitoring, real-time event listeners for reader status and payment completion, and both online and offline payment processing with automatic synchronization. Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/square-mobile-payments/index.md) to learn more about getting started with the Square Mobile Payments plugin.

# Capawesome July 2026 Update

The Capawesome July update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md) — plus two brand-new desktop platforms. Let's take a look at the most important changes.

## Blog

We published several new articles this month. Here are the highlights:

- [Electron vs. Tauri for Capacitor Apps](https://capawesome.io/blog/electron-vs-tauri-for-capacitor-apps/index.md) — A side-by-side comparison of both desktop platforms: binary size, plugin support, security model, and Live Updates.
- [Build a Desktop App with Capacitor and Electron](https://capawesome.io/blog/how-to-build-a-desktop-app-with-capacitor-and-electron/index.md) — A step-by-step walkthrough from `cap add electron` to a packaged app for macOS, Windows, and Linux.
- [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/index.md) — How to read the accelerometer, gyroscope, compass, barometer, and the other sensors in a Capacitor app.
- [Capacitor Privacy Screen: Hide Sensitive App Content](https://capawesome.io/blog/capacitor-privacy-screen-hide-app-content/index.md) — Real-world use cases for hiding app content in the app switcher and blocking screenshots.

## Cloud

### Git Integration Revamp

The Git integration in Capawesome Cloud got [its biggest upgrade yet](https://capawesome.io/blog/git-integration-revamp-in-capawesome-cloud/index.md). Git connections now live at the organization level instead of being tied to individual user accounts, which means a colleague going on vacation or leaving the company no longer breaks your team's builds. Owners and admins manage all connections on the new **Git** page in the [Capawesome Cloud Console](https://console.cloud.capawesome.io/), and every app in the organization can use them.

The new Capawesome Cloud [GitHub App](https://capawesome.io/docs/cloud/integrations/github/index.md) is now the recommended way to connect GitHub. You pick exactly which repositories it may access, it requests read-only contents and metadata, and no personal tokens are stored. Two new providers joined as well: [Gitea](https://capawesome.io/docs/cloud/integrations/gitea/index.md) for Gitea Cloud and self-hosted instances, and [Git (HTTP/S)](https://capawesome.io/docs/cloud/integrations/git/index.md) for any Git server reachable over HTTPS. Every provider also supports personal access tokens, including self-hosted and enterprise setups.

If you connected your repositories via OAuth, plan a migration: OAuth-based Git connections are deprecated and stop working on **December 31, 2026**. Existing GitHub OAuth connections can be upgraded to the GitHub App in place, without touching your builds or automations. Signing in to Capawesome Cloud with GitHub or GitLab is a separate mechanism and is not affected.

### Build Sharing

Getting a build onto a tester's device used to mean TestFlight reviews, device registration, or an APK in an email thread. With [build sharing](https://capawesome.io/blog/share-mobile-app-builds-with-testers/index.md), you can turn any successful build into a public [share link](https://capawesome.io/docs/cloud/native-builds/share-a-build/index.md): testers open the page, scan the QR code, and install the build — no Capawesome Cloud account and no app store review. Build logs and other internals stay private.

Every share can carry a description of what to test and an optional expiration date, and you can revoke it at any time. It works for Capacitor and Cordova apps as well as native Android and iOS apps.

Sharing is also available in your pipeline. The [Capawesome CLI](https://capawesome.io/docs/cloud/cli/commands/index.md) can create a share as part of the build itself:

```
npx @capawesome/cli apps:builds:create --platform android --share --json
```

Our [GitHub Action](https://capawesome.io/docs/cloud/native-builds/integrations/github-actions/index.md) has a matching `share` input, and its `shareWebUrl` and `shareQrCodeUrl` outputs let you post the QR code straight into a pull request comment — so every pull request ships with a build reviewers can install in seconds.

## Platforms

### Capacitor Electron Platform

We are excited to announce the [Capacitor Electron Platform](https://capawesome.io/docs/sdks/capacitor/electron/index.md)! It adds Electron as a target to your Capacitor project, right next to Android and iOS, so you can build desktop apps for macOS, Windows, and Linux with the `cap add`, `cap sync`, and `cap run` commands you already know. It's free, open source under the MIT license, and built as a modern replacement for the no longer actively maintained Capacitor Community Electron Platform — including a [migration guide](https://capawesome.io/blog/capacitor-community-electron-migration/index.md).

Security defaults are strict and cannot be weakened: a sandboxed renderer, context isolation, a strict Content Security Policy, and validated IPC. Plugins with an Electron implementation work out of the box, and plugins with a web implementation work automatically via fallback. It's also the first Capacitor desktop platform with built-in support for Live Updates, including automatic rollback on failed boots, and it's open to all Live Update providers. The platform requires Capacitor 6 or later and Electron 28 or later.

Read the [announcement post](https://capawesome.io/blog/announcing-the-capacitor-electron-platform/index.md) for the full story, or jump straight into our [guide on building a desktop app with Capacitor and Electron](https://capawesome.io/blog/how-to-build-a-desktop-app-with-capacitor-and-electron/index.md).

### Capacitor Tauri Platform

One day later, we released its sibling: the [Capacitor Tauri Platform](https://capawesome.io/docs/sdks/capacitor/tauri/index.md). Instead of bundling a browser, it renders your app in the webview the operating system already provides and runs its core logic in Rust. The result is a much smaller download — roughly 3 to 10 MB instead of the 80 to 150 MB an embedded Chromium needs. Its Rust core uses deny-by-default permissions, so each plugin only gets the capabilities it actually needs. It requires Capacitor 8 or later and Tauri 2 or later and is MIT-licensed as well.

The two platforms are complementary rather than competing: Electron gives you the full plugin ecosystem and Live Updates, Tauri gives you lean binaries. If you're unsure which one fits your app, our [Electron vs. Tauri comparison](https://capawesome.io/blog/electron-vs-tauri-for-capacitor-apps/index.md) walks through the trade-offs in detail. The [announcement post](https://capawesome.io/blog/announcing-the-capacitor-tauri-platform/index.md) has everything else you need to get started.

## Plugins

### 58 New Open Source Plugins

July was by far the biggest plugin month in Capawesome's history: **58 new open source Capacitor plugins** were released, covering everything from native UI primitives to hardware sensors and third-party SDKs. The complete list lives on the [Capacitor plugins page](https://capawesome.io/docs/sdks/capacitor/index.md) — here's a selection to give you an idea:

- **Native UI**: [Action Sheet](https://capawesome.io/docs/sdks/capacitor/action-sheet/index.md), [Dialog](https://capawesome.io/docs/sdks/capacitor/dialog/index.md), [Toast](https://capawesome.io/docs/sdks/capacitor/toast/index.md), [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/index.md), [In-App Browser](https://capawesome.io/docs/sdks/capacitor/in-app-browser/index.md), [System WebView](https://capawesome.io/docs/sdks/capacitor/system-webview/index.md)
- **Sensors & device state**: [Battery](https://capawesome.io/docs/sdks/capacitor/battery/index.md), [Compass](https://capawesome.io/docs/sdks/capacitor/compass/index.md), [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/index.md), [Light Sensor](https://capawesome.io/docs/sdks/capacitor/light-sensor/index.md), [Proximity Sensor](https://capawesome.io/docs/sdks/capacitor/proximity-sensor/index.md), [Thermal State](https://capawesome.io/docs/sdks/capacitor/thermal-state/index.md)
- **Security & identity**: [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/index.md), [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/index.md), [Permissions](https://capawesome.io/docs/sdks/capacitor/permissions/index.md), [Root Detection](https://capawesome.io/docs/sdks/capacitor/root-detection/index.md), [App Integrity](https://capawesome.io/docs/sdks/capacitor/app-integrity/index.md)
- **Files & documents**: [PDF Generator](https://capawesome.io/docs/sdks/capacitor/pdf-generator/index.md), [PDF Viewer](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/index.md), [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/index.md), [Exif](https://capawesome.io/docs/sdks/capacitor/exif/index.md)
- **System integration**: [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/index.md), [Wallet](https://capawesome.io/docs/sdks/capacitor/wallet/index.md), [Alarm](https://capawesome.io/docs/sdks/capacitor/alarm/index.md), [App Icon](https://capawesome.io/docs/sdks/capacitor/app-icon/index.md), [Localization](https://capawesome.io/docs/sdks/capacitor/localization/index.md), [Node.js](https://capawesome.io/docs/sdks/capacitor/nodejs/index.md)
- **Third-party SDKs**: [Crisp](https://capawesome.io/docs/sdks/capacitor/crisp/index.md), [Intercom](https://capawesome.io/docs/sdks/capacitor/intercom/index.md), [Intune](https://capawesome.io/docs/sdks/capacitor/intune/index.md), [YouTube Player](https://capawesome.io/docs/sdks/capacitor/youtube-player/index.md)

Two of them already received their first feature updates. The [Capacitor PDF Viewer plugin](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/index.md) gained a `showShareButton` option that adds a share button to the viewer toolbar on Android and iOS, and the [Capacitor Volume plugin](https://capawesome.io/docs/sdks/capacitor/volume/index.md) added a `volumeButtonReleased` event on Android, so you can react to a hardware volume button being released and not just pressed. The [Capacitor Privacy Screen plugin](https://capawesome.io/docs/sdks/capacitor/privacy-screen/index.md) also got an important fix: on iOS, the privacy screen no longer appears during system dialogs such as permission or biometric prompts.

### ML Kit

We released [Capacitor ML Kit 8.2.0](https://capawesome.io/blog/capacitor-mlkit-8-2-0-release/index.md), the biggest release in the project's history, with 14 new plugins that complete our coverage of Google's ML Kit APIs. On the vision side, there are new plugins for [text recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/text-recognition/index.md), [image labeling](https://capawesome.io/docs/sdks/capacitor/mlkit/image-labeling/index.md), [object detection](https://capawesome.io/docs/sdks/capacitor/mlkit/object-detection/index.md), [pose detection](https://capawesome.io/docs/sdks/capacitor/mlkit/pose-detection/index.md), and [digital ink recognition](https://capawesome.io/docs/sdks/capacitor/mlkit/digital-ink-recognition/index.md). For natural language, [smart reply](https://capawesome.io/docs/sdks/capacitor/mlkit/smart-reply/index.md), [entity extraction](https://capawesome.io/docs/sdks/capacitor/mlkit/entity-extraction/index.md), and [language identification](https://capawesome.io/docs/sdks/capacitor/mlkit/language-identification/index.md) joined the collection.

The most interesting addition is a set of six GenAI plugins that run Gemini Nano directly on the device, including [GenAI Prompt](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-prompt/index.md), [GenAI Summarization](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-summarization/index.md), and [GenAI Image Description](https://capawesome.io/docs/sdks/capacitor/mlkit/genai-image-description/index.md). Everything runs on-device: no server, no API keys, and no per-request costs. Head over to the [release post](https://capawesome.io/blog/capacitor-mlkit-8-2-0-release/index.md) for the full list and usage examples.

### Age Signals

The [Capacitor Age Signals plugin](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) was updated to Play Age Signals `0.0.4`. This is a breaking change, so check the `BREAKING.md` file in the repository before upgrading. In return, error codes from the Play Age Signals library are now mapped properly, which makes failures far easier to handle.

The release also adds two iOS methods. Use [`getRegulatoryRequirements()`](https://capawesome.io/docs/sdks/capacitor/age-signals/#getregulatoryrequirements) to find out whether the user is in a region that requires age assurance and which regulatory features your app must support, and [`showSignificantUpdateAcknowledgment(...)`](https://capawesome.io/docs/sdks/capacitor/age-signals/#showsignificantupdateacknowledgment) to present the system interface when an adult must acknowledge a significant change to your app:

```
import { AgeSignals, RegulatoryFeature } from '@capawesome/capacitor-age-signals';

const { regulatoryFeatures } = await AgeSignals.getRegulatoryRequirements();

if (regulatoryFeatures.includes(RegulatoryFeature.SignificantAppChangeRequiresAdultNotification)) {
  await AgeSignals.showSignificantUpdateAcknowledgment({
    updateDescription: 'This app now supports direct messages between users.',
  });
}
```

Both methods are available on iOS.

### SQLite

The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) added a [`closeAll()`](https://capawesome.io/docs/sdks/capacitor/sqlite/#closeall) method that closes every open database at once. This helps whenever the database identifiers are no longer available — most commonly after the web app has been reloaded and the previous identifiers are gone:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

await Sqlite.closeAll();
```

Closing databases also got safer: `close()` and `closeAll()` now roll back open transactions, so a dangling transaction no longer keeps the database file locked.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) exposes two new properties on the `Product` interface. `subscriptionOffers` contains the offers available for a subscription — on Android one entry per base plan and offer combination, on iOS exactly one entry — and `subscriptionGroupId` returns the subscription group of an auto-renewable subscription on iOS:

```
import { Purchases } from '@capawesome-team/capacitor-purchases';

const { products } = await Purchases.getProductsByIds({ productIds: ['premium_monthly'] });
const offers = products[0]?.subscriptionOffers;
```

This makes it much easier to build paywalls that show introductory pricing or free trials without hardcoding your store configuration in the app.

### OAuth

The [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) added an `additionalParameters` property to the result of [`login(...)`](https://capawesome.io/docs/sdks/capacitor/oauth/#login). Many identity providers return non-standard values from the token endpoint — a tenant ID, a session identifier, or a custom claim — and those values are no longer dropped:

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const result = await Oauth.login({ /* ... */ });
const tenantId = result.additionalParameters?.tenant_id;
```

Android reliability improved noticeably as well. `login()` and `logout()` no longer block the main thread, the in-app browser is no longer re-presented in an endless loop, and reopening the app from the launcher icon during a running flow no longer rejects with `USER_CANCELED`.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

July was about breadth. Capacitor apps now reach the desktop through two new platforms — [Electron](https://capawesome.io/docs/sdks/capacitor/electron/index.md) for the full plugin ecosystem and Live Updates, [Tauri](https://capawesome.io/docs/sdks/capacitor/tauri/index.md) for lean binaries — while Capawesome Cloud made test builds shareable with a link and moved Git connections to where they belong: your organization. Add 58 new open source plugins and 14 new ML Kit plugins, and it's the largest single month we've shipped so far. If you missed last month's news, catch up with the [June 2026 update](https://capawesome.io/blog/2026-june-update/index.md).

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to stay updated on the latest news and updates.

# Capawesome June 2026 Update

The Capawesome June update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Blog

We published several new articles this month. Here are the highlights:

- [What's New in Capacitor 8.4.0](https://capawesome.io/blog/whats-new-in-capacitor-8-4-0/index.md) — A look at the most useful changes in the latest Capacitor release, including three Android SystemBars fixes, a new `getDouble` config method, and the experimental Swift Package Manager `packageOptions`.
- [Convert Your Lovable App to iOS & Android Apps](https://capawesome.io/blog/convert-lovable-app-to-mobile-app/index.md) — How to turn a Lovable app into native iOS and Android apps with Capacitor and Capawesome Cloud — build in the cloud without a Mac and ship over-the-air updates.
- [Cordova Live Updates: A Complete Guide to OTA Updates](https://capawesome.io/blog/cordova-live-updates-guide/index.md) — A long-form guide to Cordova Live Updates: how OTA updates work, update strategies, code signing, best practices, and a real-world end-to-end example.

## Cloud

### Apache Cordova Support

This is the big one. [Capawesome Cloud now officially supports Apache Cordova](https://capawesome.io/blog/announcing-cordova-support-in-capawesome-cloud/index.md). With Ionic Appflow winding down, Cordova teams have been left without a real option for cloud builds and over-the-air updates — so we made Cordova a first-class citizen, not a compatibility checkbox.

That means native iOS and Android builds in the cloud, automated App Store and Google Play submissions, and — the part we're most excited about — over-the-air Live Updates through the brand-new [Cordova Live Update plugin](https://capawesome.io/docs/sdks/cordova/live-update/index.md). You get the same workflow Capacitor teams already rely on: push a new web build to a channel and your users receive it without waiting on app store review.

If you're on Cordova today, head over to the [announcement post](https://capawesome.io/blog/announcing-cordova-support-in-capawesome-cloud/index.md) for the full story and a step-by-step guide to get started.

### Build Stacks Refresh

We refreshed both [Capawesome Cloud build stacks](https://capawesome.io/docs/cloud/native-builds/build-stacks/index.md) used for native iOS and Android builds. The `macos-tahoe` stack now ships with [Xcode 26 and the latest CLIs](https://capawesome.io/blog/new-clis-and-xcode-26-in-capawesome-build-stacks/index.md), so you can target the newest iOS SDK and take advantage of the latest toolchain without maintaining your own build machines.

You can select the stack per build in your [build configuration](https://capawesome.io/docs/cloud/native-builds/configuration/index.md), which makes it easy to test a new toolchain on a branch before rolling it out to production.

### API Token Rotation

API tokens power your CI/CD pipelines and the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), so keeping them secure matters. You can now rotate an [API token](https://capawesome.io/docs/cloud/accounts/tokens/index.md) directly in the [Cloud Console](https://console.cloud.capawesome.io) — generating a fresh secret without deleting and recreating the token or reconfiguring every reference to its ID.

The token secret is now also shown only once, right after it is created. This one-time reveal keeps the secret out of your account after setup, so make sure to copy it into your secret manager straight away.

## Plugins

### Vault

We are excited to announce the initial release of the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md)! It provides encrypted, unlock-gated key/value storage — the foundation for password managers, authenticator apps, and app-lock screens. A single biometric or device-passcode unlock keeps the vault open for many reads and writes, instead of prompting on every access.

Call [`initialize(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#initialize) once per session, [`unlock(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#unlock) to prompt the user, then read and write freely with [`setValue(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#setvalue) and `getValue(...)` until the vault locks again:

```
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';

await Vault.initialize({ type: VaultType.Biometric });
await Vault.unlock();
await Vault.setValue({ key: 'token', value: 'abc123' });
```

It supports multiple independent vaults (via a `vaultId`) with their own keys and lock policies, configurable auto-lock when the app is backgrounded, and hardware-backed encryption (Android Keystore / iOS Keychain, AES-256-GCM). Built-in export and import make it a drop-in alternative to the discontinued Ionic Identity Vault. This is available on Android and iOS, with a `localStorage`-backed Web implementation for cross-platform development that is not intended for production use.

### SQLite

The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) can now load custom SQLite extensions on Android via the new `androidExtensions` option on the [`open(...)`](https://capawesome.io/docs/sdks/capacitor/sqlite/#open) method. This lets you add capabilities SQLite doesn't ship with out of the box — custom FTS5 tokenizers, domain-specific SQL functions, custom collations, and more:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const { databaseId } = await Sqlite.open({
  path: 'my-database.db',
  androidExtensions: [{ name: 'my_extension' }],
});
```

Loading extensions requires the bundled SQLite backend on Android. For a complete walkthrough using a custom FTS5 tokenizer as the running example, see our new guide on [how to use custom SQLite extensions with Capacitor](https://capawesome.io/blog/how-to-use-custom-sqlite-extensions-with-capacitor/index.md).

Error handling also got sharper: the plugin now includes the numeric SQLite result code in `error.data.sqliteCode`, so you can react to specific failures instead of parsing error messages.

### PostHog

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) added error tracking. Use the new [`captureException(...)`](https://capawesome.io/docs/sdks/capacitor/posthog/#captureexception) method to report caught errors to PostHog, optionally with a stack trace and custom properties:

```
import { Posthog } from '@capawesome/capacitor-posthog';

try {
  // ...
} catch (error) {
  await Posthog.captureException({ message: error.message, name: error.name });
}
```

You can also opt into automatic reporting with the new `autoCaptureExceptions` configuration option, which forwards unhandled exceptions without any manual `try`/`catch`.

### Firebase

We released [Capacitor Firebase 8.3.0](https://capawesome.io/blog/capacitor-firebase-8-3-0-release/index.md), with most of the work landing in two plugins.

#### Cloud Firestore

The [Capacitor Cloud Firestore plugin](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) gained broader data type support across all platforms — including `DocumentReference`, `Bytes`, `NaN`, and `Infinity` — so complex documents round-trip correctly on native and web.

[`getCountFromServer(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/#getcountfromserver) now accepts query constraints, letting you count only the documents that match a filter instead of an entire collection:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const { count } = await FirebaseFirestore.getCountFromServer({
  reference: 'users',
  compositeFilter: {
    type: 'and',
    queryConstraints: [
      { type: 'where', fieldPath: 'active', opStr: '==', value: true },
    ],
  },
});
```

Snapshot listeners also support a `serverTimestamps` behavior option, giving you control over how pending server timestamps are resolved while a write is in flight.

#### Remote Config

The [Capacitor Remote Config plugin](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/index.md) added two convenience methods. Use [`setDefaults(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/#setdefaults) to seed in-app default values before the first fetch, and [`getAll()`](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/#getall) to read every parameter at once:

```
import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

await FirebaseRemoteConfig.setDefaults({ defaults: { welcome_message: 'Hello' } });
const { values } = await FirebaseRemoteConfig.getAll();
```

### Live Update

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) received backport releases for Capacitor 6 (`6.9.0`) and Capacitor 7 (`7.5.0`), bringing the features from the Capacitor 8 line to older projects. If you can't upgrade to Capacitor 8 yet, you now get the same capabilities — including native channel configuration, the [`fetchChannels(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#fetchchannels) method, and the [`setConfig(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#setconfig) runtime configuration methods — without changing your major version.

All changes are additive, so your existing setup keeps working. Just bump the plugin to pick up the new methods and events.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

June was all about reach. [Official Apache Cordova support](https://capawesome.io/blog/announcing-cordova-support-in-capawesome-cloud/index.md) brought cloud builds, App Store publishing, and Live Updates to Cordova teams, while refreshed build stacks put Xcode 26 at your fingertips. On the plugins side, the brand-new [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) joined feature updates across SQLite, PostHog, and Firebase — plus Live Update backports that carry the latest features all the way back to Capacitor 6. And if you want to catch up on last month's news, take a look at the [May 2026 update](https://capawesome.io/blog/2026-may-update/index.md).

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to stay updated on the latest news and updates.

# Capawesome March 2026 Update

The Capawesome March update is here! This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Blog

We published several new articles this month. Here are some highlights:

- [Announcing Open Source AI Agent Skills for Capacitor](https://capawesome.io/blog/announcing-open-source-ai-agent-skills-for-capacitor/index.md) — We open sourced 7 AI agent skills that teach coding assistants like Claude and Cursor how to handle common Capacitor tasks, from plugin setup to version upgrades and cloud builds. If you haven't tried using AI agents with your Capacitor projects yet, this is a great place to start.
- [How to Use SPM Package Traits in Capacitor 8](https://capawesome.io/blog/how-to-use-spm-package-traits-in-capacitor/index.md) — Learn how to use Swift Package Manager package traits to conditionally enable optional plugin dependencies like SQLCipher directly from your Capacitor config.
- [How to Use Drizzle ORM with Capacitor and SQLite](https://capawesome.io/blog/how-to-use-drizzle-orm-with-capacitor-and-sqlite/index.md) — A step-by-step guide to building type-safe database layers in your Capacitor app using Drizzle ORM and the SQLite plugin.
- [How to Use Better Auth in Ionic and Capacitor Apps](https://capawesome.io/blog/how-to-use-better-auth-in-capacitor-apps/index.md) — Add mobile authentication to your Capacitor app with Better Auth, including social login with Apple and Google.

## Cloud

### iOS OTA Distribution

You can now install iOS and Android builds directly on physical devices from the Capawesome Cloud Console. Each build artifact includes an install button and a QR code that you can share with testers and stakeholders — no TestFlight review delays, no Play Store submission, and no extra setup required. Combined with [Automations](https://capawesome.io/docs/cloud/automations/index.md) and [notification integrations](https://capawesome.io/docs/cloud/integrations/index.md), you can set up a fully hands-off distribution workflow where builds are triggered on push and your QA team gets notified in Slack or Discord when a new build is ready to install.

Check out our [blog post](https://capawesome.io/blog/how-to-distribute-ios-and-android-apps-to-testers/index.md) for a detailed walkthrough of how to distribute test builds to your team.

### App Transfer

You can now transfer apps between organizations directly from the Cloud Console. This is useful when you need to move an app to a different team or consolidate projects under a single organization. All associated data — builds, channels, certificates, and destinations — moves with the app.

### Default Environments

Apps now support a default environment that is automatically applied to new builds when no environment is explicitly selected. This reduces repetitive configuration when you always build with the same environment and helps prevent accidental builds without the correct environment variables. You can set the default environment in the app settings in the [Cloud Console](https://console.cloud.capawesome.io).

### Web Certificate Support for Cloud Builds

Web certificates in PEM format were previously only supported for manually uploaded build artifacts. You can now also use them with web builds created by the Capawesome Cloud build runners, so your Live Update bundles are automatically signed during the build process. Check out the [Web Signing Certificates](https://capawesome.io/docs/cloud/native-builds/certificates/web/index.md) documentation to learn more.

### Usage Limit Notifications

Usage limit notifications previously only went to the organization owner and only when the limit was fully reached. Now, both owners and admins can receive notifications, and alerts are sent at 90% as well — giving your team a heads-up before limits are actually hit. You can configure the recipients in the organization settings in the [Cloud Console](https://console.cloud.capawesome.io).

## Plugins

### Android Foreground Service

The [Capacitor Android Foreground Service plugin](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/index.md) now supports a `notificationTapped` event listener that fires when a user taps on the foreground service notification:

```
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

await ForegroundService.addListener('notificationTapped', (event) => {
  console.log('Notification tapped:', event.notificationId);
});
```

This listener is available on Android.

### Apple Sign-In

We are excited to announce the initial release of the [Capacitor Apple Sign-In plugin](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/index.md)! This plugin lets you add Apple Sign-In to your Capacitor app on Android, iOS, and Web:

```
import { AppleSignIn } from '@capawesome/capacitor-apple-sign-in';

const result = await AppleSignIn.signIn({
  scopes: ['EMAIL', 'FULL_NAME'],
});
console.log('ID Token:', result.idToken);
```

Check out the [documentation](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/index.md) to learn more about getting started with the Apple Sign-In plugin.

### Audio Player

The [Capacitor Audio Player plugin](https://capawesome.io/docs/sdks/capacitor/audio-player/index.md) adds a `deactivateAudioSession` option to the [`stop(...)`](https://capawesome.io/docs/sdks/capacitor/audio-player/#stop) method. Set it to `false` when you plan to call `play()` again shortly after stopping, which avoids audio session interruption issues:

```
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

await AudioPlayer.stop({ deactivateAudioSession: false });
```

This option is available on Android and iOS and defaults to `true`.

### Firebase

#### Analytics

The [Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/index.md) plugin adds a new [`logTransaction(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/#logtransaction) method for logging StoreKit 2 in-app purchase transactions to Firebase Analytics on iOS:

```
import { FirebaseAnalytics } from '@capacitor-firebase/analytics';

await FirebaseAnalytics.logTransaction({
  transactionId: '123456789',
});
```

Pass the `Transaction.id` from StoreKit 2 as a string — if you're using the [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md), this is available on the transaction object. This method requires iOS 15.0 or later. On Android, in-app purchase tracking is handled automatically by Firebase.

Additionally, a new SPM package trait lets you disable IDFA collection on iOS by switching from `FirebaseAnalytics` to `FirebaseAnalyticsCore`. Check out our blog post on [SPM Package Traits in Capacitor](https://capawesome.io/blog/how-to-use-spm-package-traits-in-capacitor/index.md) for details on how to configure this.

#### Cloud Firestore

The [Cloud Firestore](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/index.md) plugin received three new features.

##### Timestamp, GeoPoint, and FieldValue Support

You can now use Firestore's native data types directly. The plugin automatically serializes and deserializes `Timestamp`, `GeoPoint`, and `FieldValue` across all methods:

```
import { FirebaseFirestore, Timestamp, GeoPoint, FieldValue } from '@capacitor-firebase/firestore';

await FirebaseFirestore.setDocument({
  reference: 'posts/abc',
  data: {
    createdAt: Timestamp.now(),
    location: new GeoPoint(48.1351, 11.5820),
    views: FieldValue.increment(1),
  },
});
```

##### Offline Persistence

New [`enablePersistence(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/#enablepersistence) and [`disablePersistence(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/#disablepersistence) methods give you explicit control over Firestore's offline cache. Both must be called before any other Firestore method:

```
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

await FirebaseFirestore.enablePersistence({
  cacheSizeBytes: 50 * 1024 * 1024,
});
```

##### Named Database Support

A new `databaseId` configuration option lets you connect to a specific Firestore database instead of the default one. This is available on Android and iOS.

#### Cloud Messaging

The [Cloud Messaging](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/index.md) plugin adds the `apnsTokenReceived` event listener that fires on iOS when the native APNs device token is received:

```
import { FirebaseMessaging } from '@capacitor-firebase/messaging';

await FirebaseMessaging.addListener('apnsTokenReceived', (event) => {
  console.log('APNs token:', event.token);
});
```

This is useful when you need the raw APNs token for third-party push services. The event is buffered and delivered as soon as a listener is registered.

#### Cloud Storage

The [Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/index.md) plugin adds a [`downloadFile(...)`](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/#downloadfile) method for downloading files directly to the device filesystem with progress tracking:

```
import { FirebaseStorage } from '@capacitor-firebase/storage';

await FirebaseStorage.downloadFile(
  { path: 'images/mountains.png', uri: 'file:///path/to/local/mountains.png' },
  (event, error) => {
    if (event?.completed) {
      console.log('Download complete!');
    }
  },
);
```

This method is available on Android, iOS, and Web.

### Live Update

The [Capacitor Live Update plugin](https://capawesome.io/docs/sdks/capacitor/live-update/index.md) now supports native channel configuration, allowing you to set a default channel directly in your native project. This is especially useful for versioned channels where the channel is tied to the native build version:

```
// Android: build.gradle
android {
    defaultConfig {
        resValue "string", "capawesome_live_update_default_channel", "production-" + defaultConfig.versionCode
    }
}
```

```
<!-- iOS: Info.plist -->
<key>CapawesomeLiveUpdateDefaultChannel</key>
<string>production-$(CURRENT_PROJECT_VERSION)</string>
```

Additionally, a new [`fetchChannels(...)`](https://capawesome.io/docs/sdks/capacitor/live-update/#fetchchannels) method lets you retrieve available public channels from Capawesome Cloud, which is useful for building channel selectors in development or QA builds.

### NFC

The [Capacitor NFC plugin](https://capawesome.io/docs/sdks/capacitor/nfc/index.md) now implements the [`isEnabled(...)`](https://capawesome.io/docs/sdks/capacitor/nfc/#isenabled) method on iOS and Web. On iOS, this reflects whether NFC reading is available on the device. On Web, it checks for Web NFC API support:

```
import { Nfc } from '@capawesome/capacitor-nfc';

const { isEnabled } = await Nfc.isEnabled();
console.log('NFC available:', isEnabled);
```

This method is now available on Android, iOS, and Web.

### PostHog

The [Capacitor PostHog plugin](https://capawesome.io/docs/sdks/capacitor/posthog/index.md) adds new configuration options. You can now set `apiHost` and `uiHost` to point to your own PostHog instance or reverse proxy, and `captureApplicationLifecycleEvents` to control whether lifecycle events are tracked:

```
import { Posthog } from '@capawesome/capacitor-posthog';

await Posthog.setup({
  apiKey: 'phc_YOUR_KEY',
  apiHost: 'https://eu.i.posthog.com',
  captureApplicationLifecycleEvents: false,
});
```

The `apiHost` and `uiHost` options are available on Android, iOS, and Web. The `captureApplicationLifecycleEvents` option is available on Android and iOS.

### SQLite

The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) now supports enabling [SQLCipher](https://www.zetetic.net/sqlcipher/) encryption via SPM package traits on iOS. Instead of manually linking SQLCipher, you can enable it directly in your Capacitor config:

```
{
  "experimental": {
    "ios": {
      "spm": {
        "swiftToolsVersion": "6.1",
        "packageTraits": {
          "@capawesome-team/capacitor-sqlite": ["SQLCipher"]
        }
      }
    }
  }
}
```

This requires Xcode 16.3 or later. Check out our blog post on [SPM Package Traits in Capacitor](https://capawesome.io/blog/how-to-use-spm-package-traits-in-capacitor/index.md) for more details.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

March was a big month for Capawesome. On the Cloud side, iOS OTA distribution and app transfers make it easier to test and manage your apps, while the Plugin updates bring native Firestore data types, a new Apple Sign-In plugin, and several quality-of-life improvements across the board. And in case you missed it, the [February 2026 update](https://capawesome.io/blog/2026-february-update/index.md) covers everything that shipped the month before.

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to stay updated on the latest news and updates.

# Capawesome May 2026 Update

The Capawesome May update is here — and it's our biggest one yet. This update includes new features and improvements for [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md) and our [Plugins](https://capawesome.io/docs/sdks/capacitor/index.md). Let's take a look at the most important changes.

## Blog

We published several new articles this month. Here are the highlights:

- [How to Use AI Agents in Capacitor App Development](https://capawesome.io/blog/how-to-use-ai-agents-in-capacitor-app-development/index.md) — AI coding agents are great at web development but tend to fall apart the moment a Capacitor project crosses into native territory. We show how to set up an agent that can confidently support you across the entire app lifecycle — scaffolding, plugins, builds, signing, and deployments.
- [Capacitor Live Updates: A Complete Guide to OTA Updates](https://capawesome.io/blog/capacitor-live-updates-guide/index.md) — A long-form guide covering how OTA updates work under the hood, the three core architectural choices (update strategy, versioning, delivery), code signing, production best practices, and a real-world end-to-end example.
- [Edge-to-Edge and Safe Areas in Capacitor: The Complete Guide](https://capawesome.io/blog/capacitor-edge-to-edge-and-safe-areas-guide/index.md) — Edge-to-edge has been one of the rougher edges of building with Capacitor. We break down how the framework now ships proper edge-to-edge support out of the box and how to handle safe areas correctly on both platforms.

## Cloud

### Capawesome Platform

This is the big one. We launched [Capawesome Platform](https://capawesome.io/blog/announcing-capawesome-platform/index.md) — Capawesome Cloud and our Insider SDKs unified under one brand, one website, one onboarding flow, and one pricing system. It's the biggest change we've ever made, and almost every detail of it came directly from your feedback.

There are now [three clear pricing tracks](https://capawesome.io/pricing/): a **Platform** track that bundles Live Updates, Native Builds, App Store Publishing, Automations, and the Insider SDKs together; a **Live Updates** track for teams that already handle their own native builds; and an **SDKs** track for businesses that just need the libraries. Every plan now comes with a **14-day trial**, and we doubled the number of included Insider SDKs across all Platform plans.

We also switched Live Updates back to **unlimited updates with MAU-based pricing** ([fair use](/legal/terms-of-service/) applies) — the simpler, more predictable model you asked us to bring back. Head over to the [announcement post](https://capawesome.io/blog/announcing-capawesome-platform/index.md) for the full story behind the change.

### Ask AI

Builds break and logs are long. Instead of scrolling through hundreds of lines of Gradle, Xcode, or npm output to find the actual error, you can now let AI do it for you. We launched [Capawesome Cloud Assist](https://capawesome.io/blog/announcing-capawesome-cloud-assist/index.md) — a new AI surface inside the Cloud Console — and its first feature is [Ask AI](https://capawesome.io/docs/cloud/assist/ask-ai/index.md).

On any failed build or deployment, members with write access see a new **Ask AI** button in the toolbar. One click turns the logs into a structured summary with three sections: the **cause** (the line that actually broke the job), an **explanation** in plain English, and a **suggested fix** — often with a ready-to-run snippet. You can copy the result straight into a PR description, a ticket, or a local AI coding agent like Claude Code or Cursor to apply the fix directly.

### Console Improvements

The [Cloud Console](https://console.cloud.capawesome.io) received a batch of quality-of-life improvements this month:

- **Dark mode** — the Console now ships with full dark mode support, easier on the eyes during late-night deploys. Toggle it anytime in your settings, or use the new `Ctrl`/`Cmd` + `.` keyboard shortcut.
- **App overview page** — each app now has a dedicated overview page that surfaces its builds and deployments at a glance, plus a new Jobs page that lists builds and deployments across your organization. You can filter both by Git commit to quickly find what shipped.
- **Deploy after build** — you can now deploy a completed build directly from the build view, without manually kicking off a separate deployment afterward.

## Plugins

### Age Signals

The [Capacitor Age Signals plugin](https://capawesome.io/docs/sdks/capacitor/age-signals/index.md) added a new `DECLARED` status and an `ageRangeDeclaration` property to better support US age verification compliance. When you check age signals, you can now react to a self-declared age range in addition to verified results:

```
import { AgeSignals } from '@capawesome/capacitor-age-signals';

const { userStatus } = await AgeSignals.checkAgeSignals();
if (userStatus === 'DECLARED') {
  // The user provided a self-declared age range.
}
```

It also introduces a dedicated `SDK_VERSION_OUTDATED` error so you can detect and handle outdated platform SDK versions gracefully.

### Audio Recorder

The [Capacitor Audio Recorder plugin](https://capawesome.io/docs/sdks/capacitor/audio-recorder/index.md) can now resume a recording automatically after an interruption — such as an incoming phone call. Pass the new `autoResumeAfterInterruption` option to `startRecording(...)` and listen for the new `recordingResumed` event:

```
import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

await AudioRecorder.startRecording({ autoResumeAfterInterruption: true });

await AudioRecorder.addListener('recordingResumed', () => {
  console.log('Recording resumed after interruption');
});
```

This is available on iOS.

### Biometrics

The [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) added three new methods to give you more insight into the device's biometric state before prompting the user:

```
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const { isLockedOut } = await Biometrics.isLockedOut();
const { isAllowed } = await Biometrics.isAllowed();
const { biometricTypes } = await Biometrics.getBiometricTypes();
```

Use `isLockedOut()` to detect when biometric authentication is temporarily blocked after too many failed attempts, `isAllowed()` to check whether the user has granted permission, and `getBiometricTypes()` to find out which biometric types the device supports.

### Bluetooth Low Energy

The [Capacitor Bluetooth Low Energy plugin](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/index.md) received two improvements. On iOS, you can now pass a `showPowerAlert` option to `initialize(...)` to control whether the system displays an alert when Bluetooth is powered off:

```
import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.initialize({ showPowerAlert: false });
```

On Android, you can now set a custom device name when advertising.

### Datetime Picker

The [Capacitor Datetime Picker plugin](https://capawesome.io/docs/sdks/capacitor/datetime-picker/index.md) gained a new `month` mode for the `present(...)` method. It lets users pick a month and year only — perfect for card expiry dates, billing periods, or a birth month:

```
import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const { value } = await DatetimePicker.present({
  mode: 'month',
});
```

This mode is locale-aware, supports min/max constraints, and respects light and dark themes. It is available on Android and iOS.

### Formbricks

We are excited to announce the initial release of the [Formbricks plugin](https://capawesome.io/docs/sdks/capacitor/formbricks/index.md)! It lets you embed [Formbricks](https://formbricks.com/) surveys natively in your app by bridging the official Formbricks iOS and Android SDKs. You can identify users, set attributes, and track in-app events to trigger the right survey at the right moment:

```
import { Formbricks } from '@capawesome/capacitor-formbricks';

await Formbricks.setup({
  appUrl: 'https://app.formbricks.com',
  environmentId: 'YOUR_ENVIRONMENT_ID',
});
await Formbricks.setUserId({ userId: 'user-123' });
await Formbricks.track({ action: 'button_pressed' });
```

This is available on Android and iOS.

### Grafana Faro

We are excited to announce the initial release of the [Grafana Faro plugin](https://capawesome.io/docs/sdks/capacitor/grafana-faro/index.md)! It integrates [Grafana Faro](https://grafana.com/oss/faro/) for frontend observability — logs, events, errors, and measurements — with native crash reporting and ANR detection on top of web auto-instrumentation. Initialize it once with your collector URL, then push logs and errors from anywhere in your app:

```
import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';

await GrafanaFaro.initialize({
  app: { name: 'my-app', version: '1.0.0', environment: 'production' },
  instrumentations: { anrTracking: true, errors: true, nativeCrashReporting: true },
  url: 'https://faro-collector.grafana.net/collect/REPLACE_ME',
});

await GrafanaFaro.pushLog({ level: 'info', message: 'User pressed sign-in button' });
```

This is available on Android, iOS, and Web.

### Media Session

The [Capacitor Media Session plugin](https://capawesome.io/docs/sdks/capacitor/media-session/index.md) now supports a custom seek offset, so you can control how many seconds the skip-forward and skip-backward controls jump on Android and iOS.

### ML Kit

#### Barcode Scanning

The [Capacitor ML Kit Barcode Scanning plugin](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/index.md) added support for the `readBarcodesFromImage(...)` method on the web. You can now scan barcodes from an existing image file across Android, iOS, and the web with a single API:

```
import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const { barcodes } = await BarcodeScanner.readBarcodesFromImage({
  path: 'path/to/image.jpg',
});
```

### Navigation Bar

We are excited to announce the initial release of the [Navigation Bar plugin](https://capawesome.io/docs/sdks/capacitor/navigation-bar/index.md)! It lets you customize the Android navigation bar from your web layer — set the background color, button style, and divider color, and toggle its visibility. For example, you can match the navigation bar to your app's theme and switch to light buttons:

```
import { NavigationBar, Style } from '@capawesome/capacitor-navigation-bar';

await NavigationBar.setColor({ color: '#ffffff' });
await NavigationBar.setStyle({ style: Style.Light });
```

This is available on Android.

### OAuth

The [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) added a `prefersEphemeralWebBrowserSession` option on iOS. When enabled, the authentication session does not share cookies or other browsing data with the user's browser, which forces a fresh login and avoids surfacing previously signed-in accounts:

```
import { OAuth } from '@capawesome-team/capacitor-oauth';

const result = await OAuth.login({
  configuration: { /* ... */ },
  prefersEphemeralWebBrowserSession: true,
});
```

This option is available on iOS.

### Purchases

The [Capacitor Purchases plugin](https://capawesome.io/docs/sdks/capacitor/purchases/index.md) now supports monthly billing plans with a 12-month commitment on iOS 26.4 and later, giving you more flexibility in how you structure subscriptions.

## Try Capawesome Cloud

If you're looking for a powerful cloud platform to build, deploy, and manage your Capacitor apps, check out [Capawesome Cloud](https://capawesome.io/docs/cloud/index.md). It provides native builds, live updates, app store publishing, and more — all in one place.

[Book a Capawesome Cloud Demo](https://cal.com/team/capawesome/cloud-demo)

## Conclusion

May was a landmark month. The launch of [Capawesome Platform](https://capawesome.io/blog/announcing-capawesome-platform/index.md) brought Cloud and our Insider SDKs together under one brand and one simpler pricing system, while [Ask AI](https://capawesome.io/blog/announcing-capawesome-cloud-assist/index.md) and Console dark mode made everyday work in the Cloud Console faster and friendlier. On the plugins side, three brand-new plugins — Navigation Bar, Grafana Faro, and Formbricks — joined a long list of feature updates across Datetime Picker, Biometrics, Audio Recorder, and more. Missed last month? The [April 2026 update](https://capawesome.io/blog/2026-april-update/index.md) has you covered.

If you have any questions or need help, feel free to join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). And don't forget to subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to stay updated on the latest news and updates.

# Alternative to Ionic Appflow

Looking for an [Ionic Appflow alternative](https://capawesome.io/alternatives/ionic-appflow/)? Ionic is shutting down Appflow on December 31, 2027, and if you ship a Capacitor or Cordova app, that deadline means finding a new home for your live updates, native builds, and app store submissions. This post is a practical look at how to choose an Appflow alternative: what matters when you evaluate one, and why Capawesome Cloud is the most direct replacement for most teams.

## Key Takeaways

- **Ionic Appflow shuts down on December 31, 2027, and [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner.** Existing customers keep access until then, but Capacitor and Cordova teams need a new home for live updates, native builds, and store publishing.
- **A real replacement covers all three jobs in one place** (live updates, native builds, and app store publishing) rather than gluing several generic services together.
- **Capawesome Cloud keeps the familiar live update API.** Its Live Update SDK uses the same `sync()` and `reload()` methods as Appflow, so migrating mostly changes an import.
- **Your Appflow configuration migrates in one command.** The Capawesome CLI imports Appflow's organization export (apps, certificates, secrets, destinations, and automations) automatically.
- **Pricing is transparent and starts low.** Live updates start at $9/month, and full-platform plans with native builds on macOS M4 hardware start at $19/month, with over-the-air updates always included.
- **It supports Capacitor, Cordova, and native iOS and Android** across all three features, just like Appflow.
- **Built for business-critical apps.** Every paid plan is backed by a contractual SLA, the platform is SOC 2 Type 2 compliant, and uptime is published on a public status page.

## Why teams are leaving Appflow now

Appflow is part of the commercial product line Ionic is winding down following its acquisition by OutSystems. Existing customers keep access until the end of 2027, which sounds far off until you remember what Appflow does for you on every release: it ships over-the-air live updates, builds your iOS and Android binaries in the cloud, and submits them to the App Store and Google Play.

Those are three separate jobs, and that's what makes the move harder than swapping one tool. Plenty of CI/CD services can build a binary, but very few also deliver live updates, and fewer still were designed for hybrid apps specifically. The task is finding a platform that covers the same ground so you don't end up gluing several services together and maintaining the seams.

## What to look for in an alternative

Before comparing products, it helps to know what separates a real Appflow replacement from a generic build service.

**It should cover all three jobs in one place.** Live updates, native builds, and store publishing belong together because they're stages of the same release. Splitting them across tools means two billing relationships, two sets of credentials, and a handoff you have to script yourself.

**It should be built for hybrid apps, not adapted to them.** General-purpose CI/CD platforms like [Codemagic](https://capawesome.io/alternatives/codemagic/) or [Bitrise](https://capawesome.io/alternatives/bitrise/) can build mobile apps, but a Capacitor or Cordova project has specific needs around web-asset bundling, the native shell, and over-the-air delivery. A platform that understands those out of the box saves you the YAML archaeology that generic runners require.

**It should match your framework.** Appflow supported Capacitor and Cordova. If your alternative only speaks Capacitor, Cordova teams are stuck. Native iOS and Android projects deserve a path too.

**The cost should be predictable.** Appflow's pricing pushed many teams to look elsewhere even before the shutdown. A good alternative bills transparently and doesn't make you pay separately for builds and updates.

**It should be here in five years.** You're migrating precisely because a product was discontinued. Active maintenance, a public roadmap, and open-source SDKs you can audit all reduce the risk of doing this again. Reliability artifacts count here too: a probe-based status page and a contractual SLA. If Capgo is on your shortlist, [Capawesome vs. Capgo: Which Is More Reliable?](https://capawesome.io/blog/capawesome-cloud-vs-capgo-reliability/index.md) compares both providers on exactly those.

**It should handle security properly.** Signing certificates, store credentials, and update bundles are sensitive. Encryption, isolated build environments, and signed bundles matter when you're handing a platform the keys to your release.

## Alternatives at a glance

Here's how the candidates compare on the jobs Appflow actually did for you:

| Feature                                   | Ionic Appflow | Capawesome Cloud | Capgo | VoltBuilder |
| ----------------------------------------- | ------------- | ---------------- | ----- | ----------- |
| Live updates                              | ✅            | ✅               | ✅    | ❌          |
| Cloud native builds                       | ✅            | ✅               | ✅    | ✅          |
| App store publishing                      | ✅            | ✅               | ✅    | ✅          |
| Cordova live updates                      | ✅            | ✅               | ✅    | ❌          |
| Cordova native builds                     | ✅            | ✅               | ❌    | ✅          |
| Native iOS and Android projects           | ✅            | ✅               | ❌    | ❌          |
| Git integrations                          | ✅            | ✅               | ❌    | ❌          |
| Git-triggered build automations           | ✅            | ✅               | ❌    | ❌          |
| Cloud certificate management              | ✅            | ✅               | ❌    | ❌          |
| Build environments with secrets           | ✅            | ✅               | ❌    | ❌          |
| Automatic rollback of broken updates      | ❌            | ✅               | ✅    | ❌          |
| One-command import of your Appflow export | —             | ✅               | ❌    | ❌          |
| Open to new customers                     | ❌            | ✅               | ✅    | ✅          |

Capawesome Cloud is the only Appflow alternative that replaces the complete workflow, from the connected Git repository through automated, signed builds to store submission, rather than individual features. The comparison is based on each vendor's public documentation and pricing pages as of September 2026.

## Why Capawesome Cloud is the most direct replacement

[Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Appflow and its Enterprise plugins. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

Capawesome Cloud was built for the exact audience leaving Appflow: teams shipping Capacitor and Cordova apps that want live updates, native builds, and store publishing from a single platform. It covers the same three pillars Appflow did, which is why most teams treat it as a drop-in rather than a rearchitecture.

**Live updates** ship bug fixes and features straight to your users' devices without an app store review. [Capawesome Cloud Live Updates](https://capawesome.io/docs/cloud/live-updates/index.md) uses the same `sync()` and `reload()` methods as the Appflow SDK, so existing code mostly changes its import. On top of that you get delta updates that download only changed files, automatic rollback when an update fails its health check, [gradual rollouts](https://capawesome.io/docs/cloud/live-updates/rollouts/index.md) by percentage, and channels for staging and production.

**Native builds** compile your iOS and Android apps in the cloud with no runners to maintain. [Capawesome Cloud Native Builds](https://capawesome.io/docs/cloud/native-builds/index.md) replaces Appflow's build pipeline with a single `capawesome.config.json` file instead of long YAML, and runs on M4 hardware that produces builds 3-5x faster than typical CI/CD platforms. You can trigger a build from any machine with the [Capawesome CLI](https://capawesome.io/docs/cloud/cli/index.md), including Windows and Linux, with no local Xcode required. When snapAddy [moved its builds over](https://capawesome.io/blog/announcing-capawesome-cloud-native-builds/index.md), build times dropped from 17 minutes to 5.

**App store publishing** sends finished builds to TestFlight, the App Store, and Google Play. [Capawesome Cloud App Store Publishing](https://capawesome.io/docs/cloud/app-store-publishing/index.md) lets you configure each store destination once and then submit with a single command or [automatically after every successful build](https://capawesome.io/docs/cloud/automations/index.md).

## It works with your stack

Like Appflow, Capawesome Cloud supports Capacitor, Cordova, and native iOS and Android projects across all three features. Cordova teams in particular now have a first-class home, with out-of-the-box native builds and over-the-air updates through the Cordova Live Update plugin. If that's you, [Announcing Cordova Support in Capawesome Cloud](https://capawesome.io/blog/announcing-cordova-support-in-capawesome-cloud/index.md) covers what's available in detail.

## What it costs

Cost is one of the most common reasons teams start looking. Capawesome Cloud bills transparently and, unlike most build services, includes live updates in the same plan rather than charging for them separately. Plans start at $19/month for the full platform (200 build minutes included), or $9/month if you only need live updates. Here's how a comparable volume of build minutes compares across platforms:

| Platform         | Build Minutes | Price     | Default Hardware | Live Updates Included |
| ---------------- | ------------- | --------- | ---------------- | --------------------- |
| Capawesome Cloud | 500           | $49/month | macOS M4         | Yes                   |
| GitHub Actions   | 600           | $48/month | macOS M1         | No                    |
| Codemagic        | 600           | $57/month | macOS M2         | No                    |
| Bitrise          | 600           | $99/month | macOS M2         | No                    |

Capawesome runs the newest hardware and folds in over-the-air updates that the others bill separately. Because builds are 3-5x faster on M4, those minutes also stretch further than the raw numbers suggest. There's a 14-day free trial, and full numbers are on the [pricing page](/pricing/). Prices are current as of September 2026.

[snapAddy](https://capawesome.io/blog/case-study-snapaddy-live-updates/index.md), which delivers live updates to over 1,000,000 installations, [reduced its live update costs by over 90%](https://capawesome.io/solutions/white-label/) after switching while gaining features it didn't have before.

## Built to be trusted

Migrating your release pipeline means handing a platform your signing keys and your users' update channel. Capawesome Cloud encrypts all certificates and secrets at rest and in transit, runs every build in an isolated environment, and is SOC 2 compliant with annual third-party audits. You can [sign your live update bundles](https://capawesome.io/docs/cloud/live-updates/code-signing/index.md) so devices verify their authenticity, and the Live Update SDKs are open source, so you can read exactly what they collect and send.

For businesses and enterprises, reliability is usually the deciding factor. Capawesome Cloud backs every paid plan with a contractual SLA including service credits (see our [service level agreement](https://capawesome.io/sla/) for the availability targets) and publishes its uptime on a [public status page](https://status.capawesome.io/). SSO, [audit logs](https://capawesome.io/docs/cloud/organizations/audit-logs/index.md), and [network restrictions](https://capawesome.io/docs/cloud/organizations/network-restrictions/index.md) are available without a custom enterprise contract, and an optional EU proxy keeps end-user connection data away from US providers.

The other half of trust is whether someone answers when something breaks. That tends to be where teams notice the difference:

> "Migrating from Appflow was a breeze — we were up and running in no time, with way less friction than anticipated. What really sets Capawesome apart is the support. The team is incredibly responsive and genuinely helpful." — Dan Ziv, Head of Engineering at Greetings Island

## Switching is easier than a rebuild

Because Capawesome Cloud mirrors Appflow's three pillars and keeps the familiar live update API, moving over is closer to reconnecting your repository and swapping a plugin than rewriting your release process. The configuration doesn't even need to be recreated by hand: export your organization from the Appflow dashboard and the Capawesome CLI imports it in one command, with apps, signing certificates, environments with secrets, channels, store destinations, and automations included:

```
npx @capawesome/cli apps:import --file appflow-export.zip
```

Many teams complete the remaining live update SDK swap quickly. When you're ready to make the move, the [Migrating from Ionic Appflow](https://capawesome.io/docs/cloud/migrations/ionic-appflow/index.md) guide walks through the import, live updates, native builds, and app store publishing step by step.

## Frequently Asked Questions

### Which Appflow alternative does Ionic recommend?

Ionic officially recommends Capawesome as its preferred migration partner for Appflow, Auth Connect, Identity Vault, and Secure Storage. Capawesome Cloud replaces Appflow's live updates, native builds, and app store publishing, and the Capawesome CLI imports an Appflow organization export in one command. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

### Is Capawesome Cloud a drop-in replacement for Ionic Appflow?

For most teams, yes. Capawesome Cloud covers the same three areas as Appflow (live updates, native builds, and app store publishing) and its Live Update SDK keeps the same `sync()` and `reload()` API, so migrating is closer to reconnecting your repository and swapping a plugin than rewriting your release process.

### Can I import my Appflow apps automatically?

Yes. Export your organization from the Appflow dashboard and run the CLI's [`apps:import`](https://capawesome.io/docs/cloud/cli/commands/#appsimport) command. It recreates your apps in Capawesome Cloud, including signing certificates, environments with secrets, channels, store destinations, and automations.

### Does Capawesome Cloud support Cordova?

Yes. Like Appflow, Capawesome Cloud supports Capacitor, Cordova, and native iOS and Android projects across all features. Cordova apps get native builds, app store publishing, and over-the-air updates through the Cordova Live Update plugin.

### How does Capawesome Cloud pricing compare to Appflow?

Capawesome Cloud bills transparently and includes live updates in the same plan as native builds, rather than charging for them separately. Live updates start at $9/month, and full-platform plans at $19/month. See the [pricing page](/pricing/) for current numbers.

### Which Ionic Appflow alternative is best for businesses and enterprises?

For business-critical apps, the deciding factors are reliability and compliance. Capawesome Cloud is SOC 2 Type 2 compliant, backs every paid plan with a contractual [SLA](https://capawesome.io/sla/) and service credits, publishes its uptime on a [public status page](https://status.capawesome.io/), and offers SSO, audit logs, network restrictions, and an optional EU proxy for end-user connection data, all without a custom enterprise contract.

### Will I have to rewrite my app to migrate?

No. Because the live update API matches Appflow's and your project structure stays the same, many teams complete the live update portion of a migration quickly. The [migration guide](https://capawesome.io/docs/cloud/migrations/ionic-appflow/index.md) covers the full process.

### When does Ionic Appflow shut down?

Ionic will discontinue Appflow on December 31, 2027. Existing customers keep access until then, but planning your migration early avoids a last-minute scramble.

## Try Capawesome Cloud

The fastest way to know whether Capawesome Cloud fits is to import your Appflow export, deploy a live update, and trigger a build yourself. The 14-day free trial covers all of it.

[Try Capawesome Cloud Free](https://capawesome.io)

## Conclusion

If you ship a Capacitor or Cordova app and need live updates, native builds, and app store publishing from one platform, Capawesome Cloud is the closest match to what Appflow gave you. If you only need native builds and already run your own update mechanism, a generic CI/CD service can cover that part. Either way, start the move well before December 31, 2027.

If you're ready to plan the move, start with the [Migrating from Ionic Appflow](https://capawesome.io/docs/cloud/migrations/ionic-appflow/index.md) guide. Have questions about your specific setup? Join us on the [Capawesome Discord server](https://discord.gg/VCXxSVjefW), and [subscribe to the Capawesome newsletter](https://capawesome.io/newsletter/) to stay up to date.

# Alternative to the Capacitor Community Contacts plugin

Need a contacts management solution for your Capacitor app? While the Capacitor Community Contacts plugin provides basic contact functionality for iOS and Android, developers seeking enhanced features, web support, and professional maintenance should consider the [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin. It adds web support, contact groups, photo management, pagination, and filtering on top of the basics.

## Introduction

The Capacitor Community Contacts plugin gives developers native contact access in their Capacitor applications. It provides the functionality for retrieving, creating, and deleting contacts across iOS and Android platforms. Its limits show up once an app needs more than that: there is no web support, no update method, and no access to contact groups or contact photos.

The [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin addresses these limitations by providing a professionally maintained, feature-rich alternative that extends beyond basic contact management. It adds support for web platforms, advanced filtering, contact groups, and a modern API design.

## Differences to Capawesome Contacts

The [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin offers several advantages over the Capacitor Community Contacts plugin:

**Cross-Platform Support**: Unlike the community plugin that only supports iOS and Android, Capawesome Contacts also includes web support, allowing users to pick contacts in web applications.

**Enhanced API Design**: The plugin features a modern, promise-based API with comprehensive TypeScript definitions.

**Professional Maintenance**: As part of the Capawesome ecosystem, the plugin receives regular updates, security patches, and compatibility improvements with new Capacitor versions.

**Advanced Features**: Beyond basic CRUD operations, the plugin supports contact groups, photo management, pagination, filtering, and native contact picker integration.

**Enterprise Support**: Professional support and consulting services are available for teams requiring assistance with implementation or customization.

## Migration from Capacitor Community Contacts

Migrating from the Capacitor Community Contacts plugin involves updating your installation and adapting your API calls to the new plugin structure.

### Installation

Begin by removing the existing Capacitor Community Contacts dependency and installing the Capawesome alternative. To install the [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin, please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/contacts/#installation) section in the plugin documentation.

### Create a contact

The Capawesome plugin uses dedicated type definitions for email addresses, phone numbers, and more.

**Capacitor Community Contacts:**

```
import { Contacts } from '@capacitor-community/contacts';

const createContact = async () => {
  const result = await Contacts.createContact({
    contact: {
      name: {
        given: 'John',
        family: 'Doe'
      },
      phones: [{
        type: 'mobile',
        number: '+1234567890'
      }],
      emails: [{
        type: 'work',
        address: 'john.doe@example.com'
      }]
    }
  });
  return result.contactId;
};
```

**Capawesome Contacts:**

```
import { Contacts, EmailAddressType, PhoneNumberType } from '@capawesome-team/capacitor-contacts';

const createContact = async () => {
  await Contacts.createContact({
    contact: {
      givenName: 'John',
      familyName: 'Doe',
      phoneNumbers: [{
        value: '+1234567890',
        type: PhoneNumberType.Mobile
      }],
      emailAddresses: [{
        value: 'john.doe@example.com',
        type: EmailAddressType.Work
      }]
    }
  });
};
```

### Retrieve a contact

The Capawesome Contacts plugin offers a lot more options for retrieving contacts, including filtering and pagination:

**Capacitor Community Contacts:**

```
import { Contacts } from '@capacitor-community/contacts';

const getContact = async (contactId: string) => {
  const { contact } = await Contacts.getContact({ contactId });
  return contact;
};
```

**Capawesome Contacts:**

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const getContacts = async () => {
  const { contacts } = await Contacts.getContacts({
    fields: ['id', 'givenName', 'familyName', 'phoneNumbers', 'emailAddresses'],
    limit: 100, // Limit the number of contacts retrieved
    offset: 0, // Offset for pagination
  });
  return contacts;
};

const getContactById = async (contactId: string) => {
  const { contact } = await Contacts.getContactById({ id: contactId });
  return contact;
};
```

### Update a contact

Contact updates are not directly supported in the Capacitor Community Contacts plugin, requiring a delete and recreate pattern. This has the disadvantage of losing any existing contact IDs or associations. The Capawesome plugin simplifies this with a single method for updating contacts:

**Capacitor Community Contacts:**

```
import { Contacts } from '@capacitor-community/contacts';

const updateContact = async (contactId: string) => {
  // First, delete the existing contact
  await Contacts.deleteContact({ contactId });
  // Then, create a new contact with the updated information
  await Contacts.createContact({
    contact: {
      name: {
        given: 'Jane',
        family: 'Smith'
      }
    }
  });
};
```

**Capawesome Contacts:**

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const updateContact = async (contactId: string) => {
  await Contacts.updateContactById({
    id: contactId,
    contact: {
      givenName: 'Jane',
      familyName: 'Smith'
    }
  });
};
```

### Delete a contact

Contact deletion is straightforward in both plugins:

**Capacitor Community Contacts:**

```
import { Contacts } from '@capacitor-community/contacts';

const deleteContact = async (contactId: string) => {
  await Contacts.deleteContact({ contactId });
};
```

**Capawesome Contacts:**

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const deleteContact = async (contactId: string) => {
  await Contacts.deleteContactById({ id: contactId });
};
```

### Pick a contact

The contact picker offers more selection options in the Capawesome plugin:

**Capacitor Community Contacts:**

```
import { Contacts } from '@capacitor-community/contacts';

const pickContact = async () => {
  const { contact } = await Contacts.pickContact();
  return contact;
};
```

**Capawesome Contacts:**

```
import { Contacts } from '@capawesome-team/capacitor-contacts';

const pickContacts = async () => {
  const { contacts } = await Contacts.pickContacts({
    fields: ['id', 'givenName', 'familyName', 'phoneNumbers', 'emailAddresses'],
    multiple: false
  });
  return contacts[0];
};
```

## FAQ

### Do I lose a contact's ID when I update it?

No, and this is one of the more painful gaps in the Capacitor Community plugin: it has no update method, so the common workaround is deleting the contact and recreating it, which throws away the original contact ID and breaks anything in your app that referenced it. The Capawesome Contacts plugin's `updateContactById(...)` method updates a contact in place, so the ID and any existing associations survive.

### Does the Capawesome Contacts plugin work on the web?

Yes. The Capacitor Community Contacts plugin only supports Android and iOS, so a Capacitor app that also targets the web has no way to pick or manage contacts in the browser. Capawesome Contacts adds web support on top of Android and iOS.

### Can I migrate one screen at a time, or does it have to be all at once?

You can migrate incrementally. Both plugins expose a similar shape of contact object, and the method names map closely (`createContact`, `getContacts`, `pickContacts`, `deleteContactById`), so it's reasonable to swap the import in one screen, verify it, and move to the next rather than rewriting your entire contacts layer in one pass.

### Is the Capawesome Contacts plugin free?

It's part of [Capawesome Insiders](https://capawesome.io/insiders/), a paid subscription. If you only need basic contact read/create/delete on Android and iOS, that's worth weighing against the Community plugin being free — the paid plugin's value is in the update-in-place API, web support, pagination/filtering, and maintained compatibility with new Capacitor versions.

### What happens to contact groups and photos when I migrate?

The Capacitor Community plugin doesn't expose contact groups or photo management at all, so there's nothing to migrate on that front — these are net-new capabilities in Capawesome Contacts, not a data migration concern. Existing contact data on the device (names, phone numbers, emails) is unaffected by switching plugins, since both read from the same system contacts store. See [Exploring the Capacitor Contacts API](https://capawesome.io/blog/exploring-the-capacitor-contacts-api/index.md) for how groups and photos work in practice.

## Related Posts

- [Announcing the Contacts Plugin for Capacitor](https://capawesome.io/blog/announcing-the-capacitor-contacts-plugin/index.md)
- [Exploring the Capacitor Contacts API](https://capawesome.io/blog/exploring-the-capacitor-contacts-api/index.md)

## Conclusion

If your app only reads, creates, and deletes contacts on Android and iOS, the Capacitor Community Contacts plugin covers that. Choose the [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin when you need web support, updates that keep the contact ID, contact groups, photo management, or pagination and filtering. Start with a single screen: swap the import, verify it against the mapping above, and migrate the remaining screens one at a time.

To stay updated with the latest updates, features, and news about Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/) and follow us on [X (formerly Twitter)](https://x.com/capawesomeio).

If you need assistance with migrating from the Capacitor Community Contacts plugin or implementing the [Capawesome Contacts](https://capawesome.io/docs/sdks/capacitor/contacts/index.md) plugin, the Capawesome team is available to help. [Contact us](mailto:support@capawesome.io) to get started.

# Alternative to the Capacitor Community SQLite plugin

Looking for a Capacitor SQLite solution for your Capacitor app? While the Capacitor Community SQLite plugin has been a popular choice for many developers, there's now an alternative that addresses its main drawbacks. The [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin offers a modern, enterprise-grade SQLite solution with improved security, performance, and developer experience. It is part of [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md), a paid subscription, while the Capacitor Community SQLite plugin is free and open source.

## Introduction

SQLite gives mobile and web applications a lightweight and efficient way to store structured data. The Capacitor Community SQLite plugin has been widely used in the Capacitor ecosystem, but it comes with certain limitations that can impact application performance, security, and compliance. The [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin is a modern alternative built for enterprise-grade applications that addresses the shortcomings of the Capacitor Community SQLite plugin.

## 5 reasons to consider alternatives to the Capacitor Community SQLite plugin

Before exploring alternatives, let’s take a closer look at 5 key drawbacks of the Capacitor Community SQLite plugin that have led teams to seek other solutions—such as the Capawesome SQLite plugin.

### 1. Encryption Export Regulations

When you submit your app to app stores, you upload your app to servers in specific countries (e.g., the US). If your app uses encryption, you may need to comply with export regulations that require you to declare the type of encryption used. The Capacitor Community SQLite plugin uses the [SQLCipher](https://www.zetetic.net/sqlcipher/) library, which is [subject to these regulations](https://discuss.zetetic.net/t/export-requirements-for-applications-using-sqlcipher/47). The problem here is that the Capacitor Community SQLite plugin uses the SQLCipher library even if you do not use the encryption features, which means you have to declare the use of encryption in your app as soon as you use the plugin.

Disclaimer

We aren’t attorneys or export control experts. This information is not intended as legal advice. Use it at your own risk and consult with a legal expert if you have concerns about compliance.

### 2. Performance

The Capacitor Community SQLite plugin has been known to have performance issues, especially with larger databases or complex queries. These performance bottlenecks become particularly noticeable in applications that require real-time data synchronization or handle frequent concurrent database operations.

### 3. Swift Package Manager

Modern iOS development increasingly relies on Swift Package Manager (SPM) for dependency management. Unfortunately, the Capacitor Community SQLite plugin does not support SPM, which can complicate integration with other Swift-based libraries and frameworks. This limitation becomes especially problematic for teams working with modern iOS frameworks that have moved away from CocoaPods in favor of SPM.

### 4. Web Support

There are different approaches to SQLite support in web applications. The most modern approach is to use [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly) (Wasm) to run SQLite in the browser and store the database in the Origin Private File System (OPFS) of the browser. This approach is also the only one that is officially associated with the [SQLite project](https://sqlite.org/). However, the Capacitor Community SQLite plugin does not support this approach and instead uses `sql.js` and `localforage` to store the database in IndexedDB. This complicates the setup, creates additional dependencies, and can lead to performance issues compared to the official approach.

### 5. Maintenance and Support

The Capacitor Community SQLite plugin is maintained by the community, which allows the plugin to be free and open-source but can lead to slower updates and less reliable support. While this is not a problem for many developers, those building enterprise applications may require more reliable support and maintenance options.

## Differences to the Capacitor SQLite plugin

The [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin offers 6 key advantages over the Capacitor Community alternative:

1. **Simplified API**: More intuitive API for database operations, making it easier to implement complex data management features.
1. **Optional Encryption**: Encryption is optional and only enabled when needed, avoiding unnecessary compliance burdens.
1. **WebAssembly Support**: Native WebAssembly support for web applications, providing better performance and functionality.
1. **Swift Package Manager Support**: Full support for SPM, making it easier to integrate with modern iOS projects.
1. **Enhanced Performance**: Optimized for larger databases and complex queries.
1. **Professional Support**: Direct support from the Capawesome team for all Capawesome Insiders.

## Migration from Capacitor Community SQLite plugin

Migrating from the Capacitor Community SQLite plugin to the [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin involves updating your installation, adapting your database opening logic, and adjusting your SQL execution patterns. Let's see how to do it step by step.

### Installation

First, remove the existing plugin and install the Capawesome alternative. To install the [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin, please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/sqlite/#installation) section in the SQLite capacitor plugin documentation.

### Opening a database

The database opening process differs between the two plugins. Here's how to migrate your database opening logic:

**Capacitor Community SQLite plugin:**

```
import { CapacitorSQLite, SQLiteConnection } from '@capacitor-community/sqlite';

const open = async () => {
  await CapacitorSQLite.addUpgradeStatement({
    database: 'db',
    upgrade: [
      {
        toVersion: 1,
        statements: [
          'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)'
        ]
      }
    ]
  });
  await CapacitorSQLite.open({
    database: 'db',
    readonly: false,
  });
};
```

**Capawesome SQLite plugin:**

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const open = async () => {
  const { databaseId } = await Sqlite.open({
    readOnly: false,
    path: 'db.sqlite3',
    upgradeStatements: [
      {
        version: 1,
        statements: [
          'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)'
        ]
      }
    ]
  });
};
```

### Executing SQL statements

SQL execution syntax is simplified in the Capawesome SQLite plugin:

**Capacitor Community SQLite plugin:**

```
import { CapacitorSQLite } from '@capacitor-community/sqlite';

const execute = async (databaseName: string) => {
  await CapacitorSQLite.run({
    database: databaseName,
    statement: 'INSERT INTO users (name, age) VALUES (?, ?);',
    values: ['John Doe', 30]
  });
};
```

**Capawesome SQLite plugin:**

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const execute = async (databaseId: string) => {
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, age) VALUES (?, ?);',
    values: ['John Doe', 30]
  });
};
```

### Querying data

Data querying follows a similar simplification pattern:

**Capacitor Community SQLite plugin:**

```
import { CapacitorSQLite } from '@capacitor-community/sqlite';

const query = async (databaseName: string) => {
  const result = await CapacitorSQLite.query({
    database: databaseName,
    statement: 'SELECT * FROM users WHERE age > ?;',
    values: [25]
  });
  console.log(result.values);
};
```

**Capawesome SQLite plugin:**

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const query = async (databaseId: string) => {
  const result = await Sqlite.query({
    databaseId,
    statement: 'SELECT * FROM users WHERE age > ?;',
    values: [25]
  });
  console.log(result.values);
};
```

## FAQ

##### Can I open already existing databases with the Capawesome SQLite plugin?

Yes, you can open existing databases (e.g., created with the Capacitor Community SQLite plugin) using the Capawesome SQLite plugin. Just provide the path to the existing database file when calling the `open(...)` method. If the database file does not exist, it will be created automatically.

##### Does the Capawesome SQLite plugin provide the same functionality as the Capacitor Community SQLite plugin?

Yes, at least in terms of core functionality. The Capacitor Community SQLite plugin offers a number of advanced features such as biometrics and encryption key management. However, these features are not required by most applications, so the Capawesome team has decided to move these features to separate plugins (e.g. [Capacitor Biometrics plugin](https://capawesome.io/docs/sdks/capacitor/biometrics/index.md) and [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md)). This allows you to use the Capawesome SQLite plugin without the overhead of these features if you don't need them.

## Conclusion

Switch to the [Capawesome SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) plugin if any of the five drawbacks above apply to your app: an encryption declaration you don't need, performance limits on larger databases, missing Swift Package Manager support, no WebAssembly on the web, or a need for direct support. For the full plugin documentation, see the [API Reference](https://capawesome.io/docs/sdks/capacitor/sqlite/#api). If you're adopting it fresh, [How to Use SQLite in a Capacitor App](https://capawesome.io/blog/how-to-use-sqlite-in-a-capacitor-app/index.md) walks through the setup and core operations end to end.

**Related reading:**

- [Exploring the Capacitor SQLite API](https://capawesome.io/blog/exploring-the-capacitor-sqlite-api/index.md)
- [Announcing the Capacitor SQLite Plugin](https://capawesome.io/blog/announcing-the-capacitor-sqlite-plugin/index.md)
- [Encrypting SQLite databases](https://capawesome.io/blog/encrypting-capacitor-sqlite-database/index.md)
- [Key-Value Storage with the SQLite plugin](https://capawesome.io/blog/key-value-storage-made-simple-with-the-sqlite-plugin/index.md)

**Stay updated:** [Capawesome newsletter](/newsletter/) · [X (formerly Twitter)](https://x.com/capawesomeio)

**Need help?** If you have any questions or need assistance with the Capacitor SQLite Plugin, feel free to [reach out](mailto:support@capawesome.io) to the Capawesome team. We're here to help you implement data management features in your Ionic applications.

# An Alternative to cordova-plugin-file-transfer

`cordova-plugin-file-transfer` is not dead. If you went looking for a cordova-plugin-file-transfer alternative because npm told you the plugin was deprecated, that flag came off years ago, and version 2.0.1 shipped on 10 August 2026. What has not moved is the API and the official advice that was supposed to replace it: "just use XHR", written in 2017, which pushes entire files through the WebView's JavaScript heap. This post maps every method and upload option onto the Capacitor side, compares the free official plugin with the paid Capawesome one, and says plainly which of the two you actually need.

## Key Takeaways

- `cordova-plugin-file-transfer` carried an npm deprecation flag from version 0.3.0 through 1.7.0. Version 2.0.0 shipped on 13 September 2023, over five and a half years after the previous release, and 2.0.1 followed on 10 August 2026. The plugin is maintained again, but the API has not been modernized.
- Apache's official replacement advice, a [blog post from October 2017](https://cordova.apache.org/blog/2017/10/18/from-filetransfer-to-xhr2.html), is XHR2 with `responseType = "blob"`. The plugin's own README concedes that for "large downloads, suffering from slow saving, timeouts, or crashes, this plugin is better suited for your use case".
- It is a Cordova-only plugin, supported on Android, iOS, and browser. Moving to Capacitor means picking a different plugin, not upgrading this one.
- `@capacitor/file-transfer` (official, free, currently 2.0.5) is the closest one-to-one swap: `downloadFile()`, `uploadFile()`, and an `addListener('progress')` callback. It documents no cancel, no pause and resume, and no background transfers.
- The [Capacitor File Transfer plugin](https://capawesome.io/docs/sdks/capacitor/file-transfer/index.md) from Capawesome is a paid Insiders plugin. It adds background continuation, pause and resume that survives process death, cancel, a persisted task store, automatic retries, and network constraints.

## Is cordova-plugin-file-transfer still deprecated?

No, not anymore, and this is the part most search results still get wrong. The npm deprecation flag sits on versions 0.3.0 through 1.7.0. Version 1.7.1 landed on 29 January 2018, then nothing happened for more than five years until 2.0.0 arrived on 13 September 2023. The most recent release, 2.0.1, is from 10 August 2026, and the [Apache repository](https://github.com/apache/cordova-plugin-file-transfer) is not archived.

So the plugin works, it installs without warnings, and someone is looking after it. That still leaves two problems. The README's own "Usage notice" points you at the Fetch API and XMLHttpRequest before it describes a single method, and the API itself is unchanged from the callback era: a `FileTransfer` object you construct per transfer, two success/error callbacks per call, and an assignable `onprogress` property. And it only targets `android`, `browser`, and `ios` under Cordova. There is no Capacitor build, so this is not a plugin you carry over during a migration.

## Why the official "just use XHR" advice breaks on large files

Because `responseType = "blob"` and `FormData` both route the entire file through the WebView's JavaScript heap. The pattern Apache recommends looks harmless enough for an icon or a PDF.

```
var oReq = new XMLHttpRequest();
oReq.open('GET', 'https://example.com/video.mp4', true);
oReq.responseType = 'blob';
oReq.onload = function () {
  var blob = oReq.response;
  // Now write the blob to disk...
};
oReq.send();
```

With [`responseType` set to `"blob"`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType), the response is only handed to you once the last byte has arrived, which means a 250 MB download becomes a 250 MB object in memory before anything reaches the file system. On Android that regularly ends in an `OutOfMemoryError`, and on iOS the WebView gets terminated under memory pressure. Uploads have the same shape in reverse: `FormData` reads the file into memory to build the request body. If you want the wider picture on why memory is the recurring theme in Capacitor file work, our [Capacitor File Handling: The Complete Guide](https://capawesome.io/blog/capacitor-file-handling-guide/index.md) covers the base64 and blob costs in detail.

There is a second problem that memory limits hide. An XHR lives in the WebView, so the transfer dies the moment the system suspends your app. The user switches to another app during a 500 MB download and comes back to a progress bar that reset itself.

## What should I use instead of cordova-plugin-file-transfer?

On Capacitor, use `@capacitor/file-transfer` for straightforward foreground downloads and uploads, and the [Capacitor File Transfer plugin](https://capawesome.io/docs/sdks/capacitor/file-transfer/index.md) from Capawesome when transfers need to keep running while the app is backgrounded, be paused and resumed, or be cancelled. The official plugin streams to disk instead of buffering in JavaScript, which already solves the memory problem the XHR advice creates. The Capawesome plugin goes further and moves the transfer out of the WebView entirely, into a background `URLSession` on iOS and a `dataSync` foreground service on Android. We introduced its task-based transfer model in detail in [Announcing the Capacitor File Transfer Plugin](https://capawesome.io/blog/announcing-the-capacitor-file-transfer-plugin/index.md).

One caveat before you pick: the Capawesome plugin requires a paid [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md) licence, while both the Cordova plugin and the official Capacitor one are free. This is a genuine trade-off rather than an upgrade path, so it is worth being honest about which features you actually need.

## Comparing the cordova-plugin-file-transfer alternatives

Here is how the three options line up on the capabilities that usually decide the choice.

| Capability              | XHR / fetch     | `@capacitor/file-transfer` | Capacitor File Transfer      |
| ----------------------- | --------------- | -------------------------- | ---------------------------- |
| Background continuation | No              | No                         | Yes (Android and iOS)        |
| Pause and resume        | No              | No                         | Yes, downloads only          |
| Cancel                  | Yes (`abort()`) | No                         | Yes                          |
| Progress events         | Yes             | Yes                        | Yes, throttled to ~100 ms    |
| Automatic retries       | No              | No                         | Yes (`maxRetries`)           |
| Wi-Fi-only constraint   | No              | No                         | Yes (`network: 'unmetered'`) |
| Persisted task list     | No              | No                         | Yes                          |
| Web support             | Yes             | Yes                        | No                           |
| Price                   | Free            | Free                       | Paid (Insiders)              |

Read the columns as three different jobs. XHR and fetch are fine for small payloads where the file comfortably fits in memory, `@capacitor/file-transfer` is the right default for anything that just needs to reach disk without blocking the UI, and the Capawesome plugin is for transfers whose failure the user would actually notice, such as offline video packs, course material, or media uploads over a shaky connection.

## Migrating from cordova-plugin-file-transfer

The shape of the change matters more than the individual renames. In Cordova, you construct a `FileTransfer` object per transfer and pass in the callbacks that will report the outcome. In the Capawesome plugin, you start a task, get an `id` back immediately, and observe the outcome through events. Here is how the methods and properties map across.

| `cordova-plugin-file-transfer`                   | Capacitor File Transfer                                                                                                                                                                                                             |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `new FileTransfer()`                             | No object. Each call returns a transfer `id`                                                                                                                                                                                        |
| `ft.download(source, target, win, fail)`         | [`startDownload({ url, path })`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#startdownload) → `{ id }`                                                                                                                 |
| `ft.upload(fileURL, server, win, fail, options)` | [`startUpload({ url, path })`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#startupload) → `{ id }`                                                                                                                     |
| `ft.onprogress = (e) => …` (`loaded` / `total`)  | [`addListener('transferProgress', …)`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#addlistenertransferprogress-) (`bytes` / `totalBytes` / `progress`)                                                                 |
| `successCallback`                                | `transferCompleted` event (`path`, `responseCode`, `responseBody`)                                                                                                                                                                  |
| `errorCallback` + `FileTransferError.code` 1–5   | `transferFailed` event (`errorCode`, `message`, `responseCode`)                                                                                                                                                                     |
| `ft.abort()`                                     | [`cancelTransferById({ id })`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#canceltransferbyid), which deletes partially transferred data                                                                               |
| *No equivalent*                                  | [`pauseTransferById`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#pausetransferbyid), `resumeTransferById`, `getTransferById`, [`getTransfers`](https://capawesome.io/docs/sdks/capacitor/file-transfer/#gettransfers) |
| *No equivalent*                                  | Background continuation, `maxRetries`, `network: 'unmetered'`                                                                                                                                                                       |

The upload options are where a mechanical find-and-replace will bite you, because two of them changed their defaults rather than just their names.

| `FileUploadOptions`               | Replacement                             |
| --------------------------------- | --------------------------------------- |
| `fileKey` (default `file`)        | `fileField` (default `file`)            |
| `fileName` (default `image.jpg`)  | Derived from `path`, no separate option |
| `httpMethod` (`POST`              | `PUT`)                                  |
| `mimeType` (default `image/jpeg`) | `mimeType`, with no default             |
| `params`                          | `formFields`                            |
| `chunkedMode` (default `true`)    | `uploadType: 'multipart' \| 'binary'`   |
| `headers`                         | `headers`                               |
| `trustAllHosts`                   | No equivalent, by design                |

### Downloads

Cordova's `download()` takes a `cdvfile://` URL as its target, or a full device path for backwards compatibility. The Capawesome plugin takes a plain device path, so this is usually the first thing you rewrite.

```
var fileTransfer = new FileTransfer();

fileTransfer.download(
  encodeURI('https://example.com/file.zip'),
  'cdvfile://localhost/persistent/file.zip',
  function (entry) {
    console.log('Download complete: ' + entry.toURL());
  },
  function (error) {
    console.log('Download failed with code ' + error.code);
  }
);
```

The same download in the new API splits into two parts: a listener that receives the outcome, and the call that starts the task.

```
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

await FileTransfer.addListener('transferCompleted', event => {
  console.log('Download complete:', event.path);
});

const { id } = await FileTransfer.startDownload({
  url: 'https://example.com/file.zip',
  path: '/path/to/destination/file.zip',
});
```

Note what `await` means here. `startDownload(...)` resolves as soon as the task has been queued, not when the file exists, so any code that reads the file has to move into the `transferCompleted` listener.

### Uploads

Uploads carry two changes worth flagging. `params` becomes `formFields`, and `mimeType` loses its `image/jpeg` default, so an upload that relied on that default will now send no MIME type at all. That is a silent behavior change your backend may or may not forgive.

```
var options = new FileUploadOptions();
options.fileKey = 'file';
options.mimeType = 'image/jpeg';
options.params = { albumId: '42' };

var fileTransfer = new FileTransfer();
fileTransfer.upload(fileURL, encodeURI('https://example.com/upload'), win, fail, options);
```

Everything moves into a single options object, and the file name is taken from `path` rather than set separately.

```
const { id } = await FileTransfer.startUpload({
  url: 'https://example.com/upload',
  path: '/path/to/source/file.jpg',
  uploadType: 'multipart',
  fileField: 'file',
  mimeType: 'image/jpeg',
  formFields: { albumId: '42' },
});
```

There is no direct flag for `chunkedMode`. If your server expects a raw request body rather than a multipart form, for example an S3 presigned URL, use `uploadType: 'binary'` with `method: 'PUT'`.

### Progress, cancel, and error handling

Progress moves from an assignable `onprogress` property to a regular listener, and the per-object `abort()` becomes an id-based cancel. Three listeners cover the states a transfer can reach.

```
await FileTransfer.addListener('transferProgress', event => {
  console.log(`${event.bytes}/${event.totalBytes}`, event.progress);
});
await FileTransfer.addListener('transferCompleted', event => {
  console.log('Completed:', event.id, event.responseCode);
});
await FileTransfer.addListener('transferFailed', event => {
  console.error('Failed:', event.errorCode, event.message);
});
```

One detail solves a bug that was hard to avoid in the Cordova version. Completed and failed events that occur while no listener is registered are retained and delivered as soon as a listener is added. In Cordova, a page navigation that tore down the callback closure meant the result was simply lost, and the transfer looked like it had hung forever.

## FAQ

### Is the Capacitor File Transfer plugin free?

No. It is an Insiders plugin, installed from the Capawesome npm registry with a licence key. See the [Installation](https://capawesome.io/docs/sdks/capacitor/file-transfer/#installation) section for the setup and the [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md) page for what a licence includes. If you need a free option, `@capacitor/file-transfer` is the one to use.

### Does it work on the web?

No. `startDownload(...)` and `startUpload(...)` reject as unavailable on the web, because the whole point of the plugin is a native background API that a browser cannot offer. The remaining methods are implemented and simply report that no transfer exists.

### Can I pause an upload?

Not in this version. Plain HTTP uploads have no standard resume mechanism, so `pauseTransferById(...)` rejects with the `TRANSFER_NOT_PAUSABLE` error code instead of pretending to suspend the request. Downloads can be paused and resumed at any time, including after process death, as long as the server honors the HTTP `Range` header.

### What happens to a transfer when the user force-quits the app?

It depends on the platform, and the plugin documents both cases rather than papering over them. On Android, the transfer is interrupted and restored as `failed`, and downloads can be resumed. On iOS, the system cancels background transfers when the user force-quits, which is documented OS behavior and cannot be worked around.

### Do I have to migrate everything at once?

No, migrate per call site. The Cordova plugin and the Capacitor plugins never coexist in the same project anyway, so the migration happens as part of the wider Cordova-to-Capacitor move, and each transfer can be rewritten independently.

## Need Help Migrating Off Cordova?

Moving a real app off Cordova touches more than file transfers, and the plugins with no direct Capacitor equivalent are usually what stalls the project. We do this migration work with teams regularly and can walk through your plugin list with you.

[Book a Free Consultation](https://cal.com/team/capawesome/ionic-appflow-migration)

## Conclusion

The awkward part of replacing `cordova-plugin-file-transfer` is that there is no single successor. There is a free plugin that matches the old API almost line for line, and a paid one built around a different model where transfers are tasks that outlive the WebView. The size of your files and whether users are allowed to leave the app mid-transfer decide which of the two you need, and for a lot of apps the free one is genuinely enough.

If you are working through a broader Cordova migration, our post on the [Cordova Hot Code Push Alternative for OTA Updates](https://capawesome.io/blog/cordova-hot-code-push-alternative/index.md) covers another plugin with no drop-in successor, and [Exploring the Capacitor File Compressor API](https://capawesome.io/blog/exploring-the-capacitor-file-compressor-api/index.md) is worth a read if you are shrinking files before uploading them. If your transfers write to Android's shared directories, [Android Scoped Storage in Capacitor Apps, Explained](https://capawesome.io/blog/android-scoped-storage-in-capacitor-apps/index.md) explains which destinations still work without extra permissions.

Questions about a specific migration case? Join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW) and ask, or subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/) to hear about new plugins and updates.

# Alternative to the Ionic Auth Connect Plugin

Looking for an Ionic Auth Connect alternative for your Capacitor app? Ionic [announced the discontinuation of its commercial products](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) on February 11, 2025, and Auth Connect reaches its end of life on December 31, 2027. The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) provides a production-ready replacement that supports OAuth 2.0 and OpenID Connect with PKCE across Android, iOS, and Web.

## Key Takeaways

- Ionic announced the discontinuation of its commercial products on February 11, 2025. Auth Connect sunsets on December 31, 2027, and [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner.
- The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) is an actively maintained replacement for the discontinued Ionic Auth Connect plugin.
- It implements the OAuth 2.0 Authorization Code flow with PKCE and supports OpenID Connect on Android, iOS, and Web.
- A single universal API works with any compliant provider: Auth0, Azure AD, Amazon Cognito, Okta, OneLogin, and Google.
- Automatic OpenID Connect discovery means you only provide the issuer URL instead of the full discovery URL.
- Migration is mostly a method-for-method swap, with no upfront setup call required.
- Pair it with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) for encrypted token storage.

## Why migrate from Ionic Auth Connect?

Ionic Auth Connect has been a popular choice for adding OAuth and OpenID Connect authentication to Capacitor apps. It handled login flows, token management, and session handling across platforms. However, following Ionic's acquisition by OutSystems, Ionic [announced on February 11, 2025](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) that it would discontinue its commercial products: new sales stopped immediately, and maintenance is winding down over multiple years. For Auth Connect, the sunset takes effect on December 31, 2027. After that end-of-life date, the plugin receives no further updates. Since authentication sits on the critical path of most apps, teams need a replacement that keeps their login flows secure and up to date.

[Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Auth Connect, alongside Appflow, Identity Vault, and Secure Storage. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) fills this gap. It implements the OAuth 2.0 Authorization Code flow with PKCE, supports automatic OpenID Connect discovery, and works with any compliant provider, including Auth0, Azure AD, Amazon Cognito, Okta, OneLogin, and Google.

## Feature Comparison

Here's how the two plugins stack up:

| Feature                             | Ionic Auth Connect                 | Capawesome OAuth                                                                                                        |
| ----------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| OAuth 2.0 Authorization Code + PKCE | Yes                                | Yes                                                                                                                     |
| OpenID Connect support              | Yes                                | Yes                                                                                                                     |
| Automatic endpoint discovery        | Yes                                | Yes                                                                                                                     |
| Token refresh                       | Yes                                | Yes                                                                                                                     |
| ID token decoding                   | Yes                                | Yes                                                                                                                     |
| Access token expiration check       | Yes                                | Yes                                                                                                                     |
| Multi-provider support              | Yes                                | Yes                                                                                                                     |
| Android support                     | Yes                                | Yes                                                                                                                     |
| iOS support                         | Yes                                | Yes                                                                                                                     |
| Web support                         | Yes                                | Yes                                                                                                                     |
| Secure token storage                | Separate plugin                    | Works with [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) |
| Actively maintained                 | No (end of life December 31, 2027) | Yes                                                                                                                     |

The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) covers the core authentication functionality most teams need.

AI-Assisted Migration

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration` and use the following prompt with your preferred AI coding assistant:

```
Use the `ionic-enterprise-sdk-migration` skill from `capawesome-team/skills` to help me migrate from Ionic Auth Connect to the Capawesome OAuth plugin.
```

## Migration from Auth Connect

Migrating from Ionic Auth Connect to the Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) is mostly a method-for-method swap. The following sections walk through each common operation with side-by-side code examples.

### Installation

Begin by removing the existing Auth Connect dependency and installing the Capawesome alternative, if you haven't already. To install the Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md), please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/oauth/#installation) section in the plugin documentation.

### Setup

Auth Connect requires an explicit setup step before use. The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) doesn't need any upfront configuration. You pass all required options directly to each method call.

**Ionic Auth Connect:**

```
import { AuthConnect, ProviderOptions } from '@ionic-enterprise/auth';

const setup = async () => {
  await AuthConnect.setup({
    platform: 'capacitor',
    logLevel: 'DEBUG',
    ios: { webView: 'private' },
    web: { uiMode: 'popup', authFlow: 'PKCE' },
  });
};
```

**Capawesome OAuth:**

```
// No setup needed — ready to use immediately
```

### Logging in

Both plugins initiate an OAuth flow, but the API differs. With the Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md), you pass the provider configuration directly to the [`login(...)`](https://capawesome.io/docs/sdks/capacitor/oauth/#login) method.

**Ionic Auth Connect:**

```
import { AuthConnect, Auth0Provider } from '@ionic-enterprise/auth';

const login = async () => {
  const provider = new Auth0Provider();
  const result = await AuthConnect.login(provider, {
    audience: 'https://api.example.com',
    clientId: 'YOUR_CLIENT_ID',
    discoveryUrl: 'https://example.auth0.com/.well-known/openid-configuration',
    redirectUri: 'com.example.app://callback',
    scope: 'openid profile email offline_access',
    logoutUrl: 'com.example.app://logout',
  });
  return result;
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const login = async () => {
  const result = await Oauth.login({
    issuerUrl: 'https://example.auth0.com',
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'com.example.app://oauth/callback',
    scopes: ['openid', 'profile', 'email', 'offline_access'],
    additionalParameters: { audience: 'https://api.example.com' },
  });
  return result;
};
```

A few key differences:

- **Provider configuration**: Auth Connect uses provider-specific classes (e.g., `Auth0Provider`). The Capawesome plugin uses a single, universal API for all providers.
- **Discovery**: Auth Connect requires the full discovery URL. The Capawesome plugin only needs the issuer URL and resolves the discovery document automatically.
- **Scopes**: Auth Connect takes a space-delimited string, while the Capawesome plugin takes an array.

### Handling the redirect callback

On the web platform, Auth Connect provides a `handleLoginCallback` method. The Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md) has an equivalent [`handleRedirectCallback()`](https://capawesome.io/docs/sdks/capacitor/oauth/#handleredirectcallback) method.

**Ionic Auth Connect:**

```
import { AuthConnect } from '@ionic-enterprise/auth';

const handleCallback = async () => {
  const result = await AuthConnect.handleLoginCallback(window.location.href);
  return result;
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const handleCallback = async () => {
  const result = await Oauth.handleRedirectCallback();
  return result;
};
```

This step is only required on the web. On Android and iOS, the redirect is handled natively.

### Refreshing tokens

Token refresh follows a similar pattern. Auth Connect uses a combined `AuthResult` object, while the Capawesome plugin takes individual parameters.

**Ionic Auth Connect:**

```
import { AuthConnect, Auth0Provider } from '@ionic-enterprise/auth';

const refreshSession = async (authResult) => {
  const provider = new Auth0Provider();
  const newResult = await AuthConnect.refreshSession(provider, authResult);
  return newResult;
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const refreshToken = async (refreshToken: string) => {
  const result = await Oauth.refreshToken({
    issuerUrl: 'https://example.auth0.com',
    clientId: 'YOUR_CLIENT_ID',
    refreshToken,
  });
  return result;
};
```

### Checking token state

Both plugins provide utility methods for checking token availability and expiration.

**Ionic Auth Connect:**

```
import { AuthConnect } from '@ionic-enterprise/auth';

const checkTokenState = async (authResult) => {
  const isExpired = await AuthConnect.isAccessTokenExpired(authResult);
  const isAvailable = await AuthConnect.isAccessTokenAvailable(authResult);
  const isRefreshAvailable = await AuthConnect.isRefreshTokenAvailable(authResult);
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const checkTokenState = async (
  accessToken: string,
  accessTokenExpirationDate: number,
  refreshToken: string
) => {
  const { isExpired } = await Oauth.isAccessTokenExpired({
    accessTokenExpirationDate,
  });
  const { isAvailable } = await Oauth.isAccessTokenAvailable({
    accessToken,
  });
  const { isAvailable: isRefreshAvailable } = await Oauth.isRefreshTokenAvailable({
    refreshToken,
  });
};
```

The main difference is that Auth Connect operates on the `AuthResult` object, while the Capawesome plugin takes individual values. This gives you more flexibility in how you store and manage your tokens.

### Decoding the ID token

Both plugins can decode JWT ID tokens locally.

**Ionic Auth Connect:**

```
import { AuthConnect } from '@ionic-enterprise/auth';

const decodeToken = async (authResult) => {
  const decoded = await AuthConnect.decodeToken('id', authResult);
  return decoded;
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const decodeIdToken = async (idToken: string) => {
  const { header, payload } = await Oauth.decodeIdToken({
    token: idToken,
  });
  return payload;
};
```

### Logging out

Both plugins support ending the user's session through the provider's end-session endpoint.

**Ionic Auth Connect:**

```
import { AuthConnect, Auth0Provider } from '@ionic-enterprise/auth';

const logout = async (authResult) => {
  const provider = new Auth0Provider();
  await AuthConnect.logout(provider, authResult);
};
```

**Capawesome OAuth:**

```
import { Oauth } from '@capawesome-team/capacitor-oauth';

const logout = async (idToken: string) => {
  await Oauth.logout({
    issuerUrl: 'https://example.auth0.com',
    idToken,
    postLogoutRedirectUrl: 'com.example.app://oauth/logout',
  });
};
```

## Can I keep using Ionic Auth Connect?

For a while, yes. Ionic has offered active subscribers perpetual, self-support licenses in 2026, so existing apps won't stop working overnight. However, the code is effectively frozen: there are no new features, no compatibility updates for future Android, iOS, or Capacitor releases, and no patches. With the end of life set for December 31, 2027, plan your migration before an OS or Capacitor update breaks your authentication flow with no fix available.

## Need Help Migrating?

Prefer to hand the migration off? The Capawesome team can do it for you. From a single-provider login flow to a multi-provider setup with custom token handling, our dedicated migration service moves your authentication over with minimal downtime and little effort on your side.

[Book a Free Consultation](https://cal.com/team/capawesome/ionic-appflow-migration)

## FAQ

### Which Auth Connect alternative does Ionic recommend?

Ionic officially recommends Capawesome as its preferred migration partner for Auth Connect, together with Appflow, Identity Vault, and Secure Storage. The Capacitor OAuth plugin is the replacement Ionic points its customers to. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

### Is the Capawesome OAuth plugin free?

No, it's part of [Capawesome Insiders](https://capawesome.io/insiders/), a paid subscription. It's a replacement for Auth Connect's own commercial license, which no longer accepts new customers and receives no compatibility updates past its December 31, 2027 end of life.

### Does the OAuth plugin store tokens for me?

No, and this is a deliberate difference from some all-in-one auth SDKs. The plugin returns the access token, refresh token, and ID token from `login()`, `refreshToken()`, and similar methods, but storing them securely is left to your app. Pair it with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) to persist tokens in encrypted, platform-native storage rather than rolling your own.

### Which identity providers does it work with?

Any provider that implements standard OAuth 2.0 Authorization Code flow with PKCE and OpenID Connect discovery. The plugin has been used successfully with Auth0, Azure AD, Amazon Cognito, Okta, OneLogin, and Google. Unlike Auth Connect's provider-specific classes (`Auth0Provider`, etc.), it's a single universal API, so switching providers later doesn't mean switching plugin APIs too.

### Can I keep using Ionic Auth Connect in the meantime?

For now, yes. Apps built against it keep working, and Ionic has offered active subscribers perpetual, self-support licenses. But the code is effectively frozen: no new features, no compatibility fixes for future Android, iOS, or Capacitor releases. Planning the migration before an OS update breaks your login flow with no available fix is safer than waiting for the December 31, 2027 end-of-life date to force the issue.

### Do I have to migrate every login flow at once?

No. The method names map closely enough (`login`, `handleRedirectCallback`, `refreshToken`, `logout`) that migrating provider-by-provider or screen-by-screen is reasonable, especially if you support multiple identity providers and want to validate one before moving the rest.

## Conclusion

Start the migration well before the December 31, 2027 end-of-life date, and do it one flow at a time. Point a single provider's login at the Capawesome [Capacitor OAuth plugin](https://capawesome.io/docs/sdks/capacitor/oauth/index.md), verify login, token refresh, and logout on Android, iOS, and Web, then move the remaining flows over. Add the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) in the same step to store the returned tokens in encrypted, platform-native storage.

**Related reading:**

- [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/index.md)
- [Alternative to the Ionic Identity Vault Plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/index.md)
- [Announcing the Capacitor OAuth Plugin](https://capawesome.io/blog/announcing-the-capacitor-oauth-plugin/index.md)
- [How to Add Authentication to a Capacitor App](https://capawesome.io/blog/how-to-add-authentication-to-a-capacitor-app/index.md)

**Stay updated:**

Join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW) to ask questions and connect with the community, and subscribe to the [Capawesome newsletter](/newsletter/) for the latest news about Capawesome, Capacitor, and the Ionic ecosystem.

**Need help migrating from Auth Connect?** [Contact us](mailto:support@capawesome.io) to get started.

# Alternative to the Ionic Identity Vault Plugin

Looking for a way to protect sensitive data and authenticate users in your Capacitor app? With [Ionic discontinuing](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) their commercial Identity Vault plugin, developers need a reliable alternative for biometric authentication (Face ID, fingerprint) and secure session management. The [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) from Capawesome is a near drop-in replacement: same active lock pattern, the same method names for the core operations, multi-vault support out of the box, and no enterprise subscription required.

For background on the plugin, see our [announcement post](https://capawesome.io/blog/announcing-the-capacitor-vault-plugin/index.md).

## Key Takeaways

- [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Identity Vault, alongside Appflow, Auth Connect, and Secure Storage.
- The [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) is a near drop-in replacement for Ionic Identity Vault, with no enterprise subscription required.
- Core operations (`unlock`, `lock`, `setValue`, `getValue`, `removeValue`, `clear`) keep the same method names; most calls switch from positional arguments to an options object.
- The constructor `new Vault(config)` becomes a single static `initialize(...)` call, and `type` + `deviceSecurityType` collapse into one `VaultType` enum.
- Multi-vault support is built in via the `vaultId` option on every method.
- Stored data can't be copied across directly. Migrate it at runtime while both plugins are installed, using Identity Vault's `exportVault()` and the Capacitor Vault plugin's `importData(...)`.

## Introduction

Ionic Identity Vault combined biometric authentication, encrypted storage, and session management into a single plugin. It let developers store tokens and credentials securely, lock and unlock a vault with Face ID or fingerprint, and automatically clear sensitive data after inactivity. Following Ionic's decision to phase out their commercial products, teams need a replacement.

[Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Identity Vault, alongside Appflow, Auth Connect, and Secure Storage. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

The [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) from Capawesome was built for exactly this scenario. It covers the same surface — biometric or device-passcode unlock, a session-based lock model with auto-lock, hardware-backed key/value storage, and migration utilities — under an API that mirrors Identity Vault's most common methods. In most cases, migrating is a matter of swapping the import and adding a one-time `initialize(...)` call.

## Feature Comparison

Here's a side-by-side look at how Identity Vault features map to the Capacitor Vault plugin:

| Feature                    | Identity Vault                  | Capacitor Vault                                                                                                                                                  |
| -------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Initialize vault           | `new Vault(config)`             | [`Vault.initialize(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#initialize)                                                                           |
| Biometric unlock           | `Vault.unlock()`                | [`Vault.unlock()`](https://capawesome.io/docs/sdks/capacitor/vault/#unlock)                                                                                      |
| Lock vault                 | `Vault.lock()`                  | [`Vault.lock()`](https://capawesome.io/docs/sdks/capacitor/vault/#lock)                                                                                          |
| Check if locked            | `Vault.isLocked()`              | [`Vault.isLocked()`](https://capawesome.io/docs/sdks/capacitor/vault/#islocked)                                                                                  |
| Store values               | `Vault.setValue(...)`           | [`Vault.setValue(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#setvalue)                                                                               |
| Retrieve values            | `Vault.getValue(...)`           | [`Vault.getValue(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#getvalue)                                                                               |
| Remove values              | `Vault.removeValue(...)`        | [`Vault.removeValue(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#removevalue)                                                                         |
| List keys                  | `Vault.getKeys()`               | [`Vault.getKeys()`](https://capawesome.io/docs/sdks/capacitor/vault/#getkeys)                                                                                    |
| Clear all data             | `Vault.clear()`                 | [`Vault.clear()`](https://capawesome.io/docs/sdks/capacitor/vault/#clear)                                                                                        |
| Device credential fallback | `DeviceSecurityType.Both`       | `VaultType.BiometricOrDevicePasscode` / `VaultType.DevicePasscode`                                                                                               |
| Auto-lock on background    | `lockAfterBackgrounded`         | `lockAfterBackgrounded`                                                                                                                                          |
| Lock / unlock events       | `onLock` / `onUnlock` callbacks | [`addListener('lock', ...)`](https://capawesome.io/docs/sdks/capacitor/vault/#addlistenerlock-)                                                                  |
| Multiple vaults            | Multiple `Vault` instances      | `vaultId` option on every method                                                                                                                                 |
| Key invalidation           | Built-in                        | `invalidateOnBiometricEnrollment`                                                                                                                                |
| Export / import data       | Manual                          | [`exportData()`](https://capawesome.io/docs/sdks/capacitor/vault/#exportdata) / [`importData(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#importdata) |
| Web fallback               | Built-in                        | `localStorage` (dev only)                                                                                                                                        |

Identity Vault's most common methods carry their names over to the Capacitor Vault plugin, so a typical migration touches the import statement, the constructor (now `initialize(...)`), and a few configuration option names.

AI-Assisted Migration

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration` and use the following prompt with your preferred AI coding assistant:

```
Use the `ionic-enterprise-sdk-migration` skill from `capawesome-team/skills` to help me migrate from Ionic Identity Vault to the Capacitor Vault plugin.
```

## Migration from Identity Vault

Migrating from Identity Vault is largely a matter of swapping the constructor for an `initialize(...)` call and updating the import path. The following sections walk through the most common scenarios.

### Installation

Begin by removing the existing Identity Vault dependency and installing the Capacitor Vault plugin. To install the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md), please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/vault/#installation) section in the plugin documentation.

### Initializing the Vault

Identity Vault uses a `new Vault(config)` constructor for each vault instance. The Capacitor Vault plugin uses a static [`initialize(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#initialize) call that takes the same shape of configuration.

**Identity Vault:**

```
import { Vault, DeviceSecurityType, VaultType } from '@ionic-enterprise/identity-vault';

const vault = new Vault({
  key: 'com.example.vault',
  type: VaultType.DeviceSecurity,
  deviceSecurityType: DeviceSecurityType.Both,
  lockAfterBackgrounded: 2000,
});
```

**Capacitor Vault:**

```
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';

const initialize = async () => {
  await Vault.initialize({
    vaultId: 'com.example.vault',
    type: VaultType.BiometricOrDevicePasscode,
    lockAfterBackgrounded: 2000,
  });
};
```

Call `initialize(...)` once per session before any other method. The `vaultId` option corresponds to Identity Vault's `key`, and `type` collapses Identity Vault's separate `type` and `deviceSecurityType` into a single enum (`Biometric`, `BiometricOrDevicePasscode`, or `DevicePasscode`).

### Biometric Authentication

Identity Vault uses `vault.unlock()` to trigger biometric authentication. The Capacitor Vault plugin uses the same method name. Only the import changes.

**Identity Vault:**

```
const unlock = async () => {
  await vault.unlock();
};
```

**Capacitor Vault:**

```
import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault';

const unlock = async () => {
  try {
    await Vault.unlock();
  } catch (error) {
    if (error.code === ErrorCode.UnlockCanceled) {
      // User dismissed the prompt
    } else if (error.code === ErrorCode.KeyInvalidated) {
      // Biometric set changed — re-enrollment required
    } else {
      throw error;
    }
  }
};
```

Typed error codes let you branch on the specific reason an unlock failed instead of catching a generic error. `UnlockCanceled` means the user dismissed the prompt; `KeyInvalidated` means the device's biometric set has changed and the vault needs to be reinitialized.

### Storing Values

Identity Vault's `setValue(...)` stores data inside the encrypted vault. The Capacitor Vault plugin uses the same method name with an options-object argument.

**Identity Vault:**

```
const storeToken = async () => {
  await vault.setValue('session_token', 'eyJhbGciOiJIUzI1NiIs...');
};
```

**Capacitor Vault:**

```
import { Vault } from '@capawesome-team/capacitor-vault';

const storeToken = async () => {
  await Vault.setValue({
    key: 'session_token',
    value: 'eyJhbGciOiJIUzI1NiIs...',
  });
};
```

### Retrieving Values

Reading a value follows the same pattern. Positional arguments become an options object.

**Identity Vault:**

```
const getToken = async () => {
  const token = await vault.getValue('session_token');
  return token;
};
```

**Capacitor Vault:**

```
import { Vault } from '@capawesome-team/capacitor-vault';

const getToken = async () => {
  const { value } = await Vault.getValue({ key: 'session_token' });
  return value;
};
```

### Removing Values

Removing a single value uses the same `removeValue` method name in both plugins.

**Identity Vault:**

```
const removeToken = async () => {
  await vault.removeValue('session_token');
};
```

**Capacitor Vault:**

```
import { Vault } from '@capawesome-team/capacitor-vault';

const removeToken = async () => {
  await Vault.removeValue({ key: 'session_token' });
};
```

### Clearing All Data

`clear()` empties the vault while preserving its configuration.

**Identity Vault:**

```
const clearVault = async () => {
  await vault.clear();
};
```

**Capacitor Vault:**

```
import { Vault } from '@capawesome-team/capacitor-vault';

const clearAll = async () => {
  await Vault.clear();
};
```

### Session Management

Identity Vault's `lockAfterBackgrounded` option ports over directly to the Capacitor Vault plugin. Set it during `initialize(...)` and the vault locks itself when the app has been backgrounded for that long. Lock and unlock callbacks are exposed as events:

```
import { Vault } from '@capawesome-team/capacitor-vault';

const setupSessionHandling = async () => {
  await Vault.addListener('lock', ({ vaultId, trigger }) => {
    // trigger is 'MANUAL' or 'TIMEOUT'
    console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`);
  });
  await Vault.addListener('unlock', ({ vaultId }) => {
    console.log(`Vault ${vaultId} unlocked.`);
  });
};
```

The `trigger` on the lock event tells you whether the vault was locked by an explicit `lock()` call (`MANUAL`) or by the auto-lock timer (`TIMEOUT`), useful when the two cases warrant different UI feedback.

### Multiple Vaults

Identity Vault supports multiple vaults via multiple `Vault` instances. The Capacitor Vault plugin supports the same through the `vaultId` option, which every method accepts:

```
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';

const initializeBoth = async () => {
  await Vault.initialize({
    vaultId: 'user-tokens',
    type: VaultType.Biometric,
  });
  await Vault.initialize({
    vaultId: 'app-settings',
    type: VaultType.BiometricOrDevicePasscode,
    lockAfterBackgrounded: 60000,
  });
};
```

Each vault keeps its own keys, lock state, and configuration, which is handy for multi-account apps or for separating data with different sensitivity levels.

### Migrating Stored Data

If your app already has data in an Identity Vault, you cannot move it across by reusing Identity Vault's keystore or keychain entries. The two plugins use incompatible storage formats: Identity Vault keeps the whole vault as a single encrypted blob (on Android partly via a closed-source dependency), while the Capacitor Vault plugin stores each value individually with its own encryption scheme. There is no way to decrypt Identity Vault's data without its proprietary implementation.

Instead, migrate the data at runtime while both plugins are still installed. Identity Vault's `exportVault()` returns a plain key/value map after the vault is unlocked, and that map has the exact shape the Capacitor Vault plugin's [`importData(...)`](https://capawesome.io/docs/sdks/capacitor/vault/#importdata) method expects, so you can bridge the two directly:

```
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';
// Your existing Identity Vault instance.
import { vault as identityVault } from './identity-vault';

const MIGRATION_KEY = 'capacitor-vault-migrated';

const migrateFromIdentityVault = async () => {
  // Skip if the migration has already been performed.
  if (localStorage.getItem(MIGRATION_KEY)) {
    return;
  }
  // Nothing to migrate if the old vault is empty.
  if (await identityVault.isEmpty()) {
    localStorage.setItem(MIGRATION_KEY, 'true');
    return;
  }

  // Unlocking prompts the user to authenticate (e.g. via biometrics).
  await identityVault.unlock();
  const data = await identityVault.exportVault();

  // Initialize the new vault and import the data.
  await Vault.initialize({ type: VaultType.Biometric });
  await Vault.unlock();
  await Vault.importData({ data });

  // Clear the old vault and mark the migration as complete.
  await identityVault.clear();
  localStorage.setItem(MIGRATION_KEY, 'true');
};
```

Run this once before removing the Identity Vault dependency. The user has to authenticate a single time to unlock the old vault. This is unavoidable, since the data is protected by the device's biometric or passcode authentication by design. Once all users have migrated (for example, after a release cycle in which everyone has opened the app at least once), you can drop Identity Vault in a follow-up release.

## FAQ

### Which Identity Vault alternative does Ionic recommend?

Ionic officially recommends Capawesome as its preferred migration partner for Identity Vault, together with Appflow, Auth Connect, and Secure Storage. The Capacitor Vault plugin is the replacement Ionic points its customers to. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

### Is the Capacitor Vault plugin free, since it doesn't need an Ionic enterprise subscription?

It doesn't require Ionic Identity Vault's enterprise subscription, but it's still a paid plugin, part of [Capawesome Insiders](https://capawesome.io/insiders/). The difference is licensing model, not price point: no per-seat enterprise contract, just a Capawesome Insiders subscription that covers this plugin alongside the rest of the catalog.

### What happens if a user's biometrics change after enrollment?

The Capacitor Vault plugin can invalidate the vault's key automatically when the device's enrolled biometrics change (fingerprint added/removed, new face enrolled) via the `invalidateOnBiometricEnrollment` option. When that happens, `unlock()` rejects with `ErrorCode.KeyInvalidated` so your app can prompt the user to reinitialize the vault.

### Does the plugin support falling back to a device passcode if biometrics aren't available?

Yes, via `VaultType.BiometricOrDevicePasscode`, the same behavior as Identity Vault's `DeviceSecurityType.Both`. Use `VaultType.DevicePasscode` if you want to skip biometrics entirely and only accept the device passcode.

### Can I run multiple vaults with different lock timeouts in the same app?

Yes. Every method takes a `vaultId` option, so a multi-account app (or one that separates high-sensitivity data like payment tokens from lower-sensitivity settings) can initialize several vaults, each with its own `lockAfterBackgrounded` timeout and lock state.

### Can I migrate existing vault data without asking users to re-authenticate?

No. This one step is unavoidable. The old vault's contents are protected by the device's biometric or passcode authentication by design, so reading them via `exportVault()` requires unlocking the Identity Vault instance first. Users authenticate once during the migration, and everything after that uses the new vault normally.

## Need Help Migrating?

If you'd rather not handle the migration yourself, the Capawesome team can take care of it for you. Whether you're dealing with a straightforward swap or a more complex setup with custom session management, we offer dedicated migration services to get you up and running with minimal downtime and effort on your end.

[Book a Free Consultation](https://cal.com/team/capawesome/ionic-appflow-migration)

## Conclusion

Plan the migration in two releases. In the first, install the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) alongside Identity Vault, swap the constructor for `initialize(...)`, and run the runtime data migration. In the second, once every user has opened the app at least once, remove the Identity Vault dependency. For every method signature and option, see the [API Reference](https://capawesome.io/docs/sdks/capacitor/vault/#api).

**Related reading:**

- [Announcing the Capacitor Vault Plugin](https://capawesome.io/blog/announcing-the-capacitor-vault-plugin/index.md)
- [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/index.md)
- [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/index.md)

**Stay updated:**

Have questions or want to share your migration experience? Join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW) to connect with the community. To stay updated with the latest updates, features, and news about Capawesome, Capacitor, and the Ionic ecosystem, subscribe to our [Capawesome newsletter](/newsletter/).

**Need help migrating from Identity Vault?** [Contact us](mailto:support@capawesome.io) to get started.

# Alternative to the Ionic Secure Storage Plugin

Looking for an Ionic Secure Storage alternative for your Capacitor app? Ionic [announced the discontinuation of its commercial products](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) on February 11, 2025, and Secure Storage reaches its end of life on December 31, 2027. Depending on your use case, the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) (key-value data), the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) (encrypted SQL databases via SQLCipher), and the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) (biometric-protected secrets) provide modern, actively maintained replacements that close the gap left by Ionic Secure Storage.

## Key Takeaways

- Ionic announced the discontinuation of its commercial products on February 11, 2025. Ionic Secure Storage sunsets on December 31, 2027, and [Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner.
- For key-value data, migrate to the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md), which uses the Android Keystore and iOS Keychain.
- For encrypted databases, migrate to the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md), which offers the same 256-bit AES encryption via SQLCipher.
- For biometric-protected secrets, use the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md), which stores key-value pairs in lockable vaults.
- All three plugins are actively maintained and stay current with the latest Capacitor versions.
- The Capawesome team offers a dedicated migration service if you'd rather not handle it yourself.

## Why migrate from Ionic Secure Storage?

Ionic Secure Storage has been a go-to solution for developers requiring encrypted local storage in their Capacitor applications. However, following Ionic's acquisition by OutSystems, Ionic [announced on February 11, 2025](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) that it would discontinue its commercial products: new sales stopped immediately, and maintenance is winding down over multiple years. For Secure Storage, the sunset takes effect on December 31, 2027. After that end-of-life date, the plugin receives no further updates. Since the plugin offered both key-value storage and SQLite database functionality with 256-bit AES encryption, teams handling sensitive data need a replacement.

[Ionic officially recommends Capawesome](https://ionic.io/blog/%f0%9f%9a%80-announcing-a-partnership-with-capawesome) as its preferred migration partner for Secure Storage, alongside Appflow, Auth Connect, and Identity Vault. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

The Capawesome plugins cover every Ionic Secure Storage use case:

- **Key-value data**: The [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) stores key-value pairs using the Android Keystore and iOS Keychain, the same security model developers relied on with Ionic Secure Storage.
- **Encrypted SQL databases**: The [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) encrypts databases with 256-bit AES via SQLCipher, a like-for-like replacement for Secure Storage's headline feature.
- **Biometric-protected secrets**: The [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) stores secrets in lockable vaults that can require biometric authentication to unlock — the use case previously covered by pairing Secure Storage with Ionic Identity Vault.

AI-Assisted Migration

For a more guided experience, add the [Capawesome skills](https://capawesome.io/docs/ai/skills/index.md) to your project with `npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration` and use the following prompt with your preferred AI coding assistant:

```
Use the `ionic-enterprise-sdk-migration` skill from `capawesome-team/skills` to help me migrate from Ionic Secure Storage to Capawesome alternatives.
```

## Migration from Ionic Secure Storage

Migrating from Ionic Secure Storage requires choosing the appropriate replacement based on your storage needs: key-value storage or SQLite database functionality. If you also need to protect individual secrets behind biometric authentication, take a look at the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md).

### Key-Value Store

For applications using Ionic Secure Storage's key-value functionality, migrate to the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md). If you'd rather keep key-value data in an encrypted SQLite database, the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) also ships a built-in key-value store. See [Key-Value Storage Made Simple with the SQLite Plugin](https://capawesome.io/blog/key-value-storage-made-simple-with-the-sqlite-plugin/index.md).

#### Installation

Begin by removing the existing Ionic Secure Storage dependency and installing the Capawesome alternative, if you haven't already. To install the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md), please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/secure-preferences/#installation) section in the plugin documentation.

#### Create a store

Unlike Ionic Secure Storage, the Capacitor Secure Preferences plugin doesn't require explicit store creation. The secure storage is automatically available after installation. Values are encrypted using the Android Keystore and stored in the iOS Keychain, so the plugin handles key management for you.

**Ionic Secure Storage:**

```
import { KeyValueStorage } from '@ionic-enterprise/secure-storage';

const createStore = async () => {
  await KeyValueStorage.create('my-secret-key');
};
```

**Capacitor Secure Preferences:**

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

// No store creation needed - ready to use immediately
```

#### Set a value

**Ionic Secure Storage:**

```
import { KeyValueStorage } from '@ionic-enterprise/secure-storage';

const setValue = async () => {
  await KeyValueStorage.set('username', 'john_doe');
};
```

**Capacitor Secure Preferences:**

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const setValue = async () => {
  await SecurePreferences.set({
    key: 'username',
    value: 'john_doe'
  });
};
```

#### Get a value

**Ionic Secure Storage:**

```
import { KeyValueStorage } from '@ionic-enterprise/secure-storage';

const getValue = async () => {
  const value = await KeyValueStorage.get('username');
  return value;
};
```

**Capacitor Secure Preferences:**

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const getValue = async () => {
  const { value } = await SecurePreferences.get({ key: 'username' });
  return value;
};
```

#### Remove a value

**Ionic Secure Storage:**

```
import { KeyValueStorage } from '@ionic-enterprise/secure-storage';

const removeValue = async () => {
  await KeyValueStorage.remove('username');
};
```

**Capacitor Secure Preferences:**

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const removeValue = async () => {
  await SecurePreferences.remove({ key: 'username' });
};
```

#### Clear the store

**Ionic Secure Storage:**

```
import { KeyValueStorage } from '@ionic-enterprise/secure-storage';

const clearStore = async () => {
  await KeyValueStorage.clear();
};
```

**Capacitor Secure Preferences:**

```
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const clearStore = async () => {
  await SecurePreferences.clear();
};
```

### SQLite

For applications using Ionic Secure Storage's SQLite functionality, migrate to the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md).

#### Installation

Begin by removing the existing Ionic Secure Storage dependency and installing the Capawesome alternative, if you haven't already. To install the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md), please refer to the [Installation](https://capawesome.io/docs/sdks/capacitor/sqlite/#installation) section in the plugin documentation.

#### Opening a database

Database initialization differs between the two solutions. Here's how to adapt your database setup:

**Ionic Secure Storage:**

```
import { SQLite } from '@ionic-enterprise/secure-storage';

const openDatabase = async () => {
  const db = await SQLite.create({
    name: 'database.db',
    location: 'default',
  });
  await db.executeSql('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)', []);
  return db;
};
```

The Capacitor SQLite plugin encrypts databases with 256-bit AES via SQLCipher. Pass an `encryptionKey` to `open(...)` to keep the same encryption guarantee Ionic Secure Storage provided:

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const openDatabase = async () => {
  const { databaseId } = await Sqlite.open({
    path: 'database.db',
    encryptionKey: 'your-secret-key',
    upgradeStatements: [
      {
        version: 1,
        statements: [
          'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)'
        ]
      }
    ]
  });
  return databaseId;
};
```

Enabling encryption

Encryption requires bundling SQLCipher in your native projects. See the [Encryption](https://capawesome.io/docs/sdks/capacitor/sqlite/#encryption) section in the plugin documentation for the platform setup, or follow the step-by-step guide in [Encrypting SQLite databases in Capacitor](https://capawesome.io/blog/encrypting-capacitor-sqlite-database/index.md). Don't hard-code the key. Store it with the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md).

#### Executing SQL statements

The two plugins differ in how they execute SQL statements:

**Ionic Secure Storage:**

```
import { SQLiteObject } from '@ionic-enterprise/secure-storage';

const insertUser = async (db: SQLiteObject, name: string, email: string) => {
  await db.executeSql(
    'INSERT INTO users (name, email) VALUES (?, ?)',
    [name, email]
  );
};
```

**Capacitor SQLite:**

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const insertUser = async (databaseId: string, name: string, email: string) => {
  await Sqlite.execute({
    databaseId,
    statement: 'INSERT INTO users (name, email) VALUES (?, ?)',
    values: [name, email]
  });
};
```

#### Querying data

The two plugins also differ in how they return query results:

**Ionic Secure Storage:**

```
import { SQLiteObject } from '@ionic-enterprise/secure-storage';

const getUsers = async (db: SQLiteObject) => {
  return new Promise((resolve) => {
    db.transaction(tx => {
      tx.executeSql('SELECT * FROM users WHERE name LIKE ?', ['%John%'], (tx, result) => {
        resolve(result.rows);
      });
    });
  });
};
```

**Capacitor SQLite:**

```
import { Sqlite } from '@capawesome-team/capacitor-sqlite';

const getUsers = async (databaseId: string) => {
  const result = await Sqlite.query({
    databaseId,
    statement: 'SELECT * FROM users WHERE name LIKE ?',
    values: ['%John%']
  });
  return result.rows;
};
```

## Can I keep using Ionic Secure Storage?

For a while, yes. Ionic has offered active subscribers perpetual, self-support licenses in 2026, so existing apps won't stop working overnight. However, the code is effectively frozen: there are no new features, no compatibility updates for future Android, iOS, or Capacitor releases, and no patches. With the end of life set for December 31, 2027, it's worth planning your migration before an OS or Capacitor update introduces an incompatibility that can no longer be fixed.

## FAQ

### Which Secure Storage alternative does Ionic recommend?

Ionic officially recommends Capawesome as its preferred migration partner for Secure Storage, together with Appflow, Auth Connect, and Identity Vault. The Capacitor SQLite and Secure Preferences plugins are the replacements Ionic points its customers to. Read [Announcing Our Official Partnership with Ionic](https://capawesome.io/blog/announcing-partnership-with-ionic/index.md) for the details.

### Which plugin should I migrate to — Secure Preferences, SQLite, or Vault?

It depends on what you were storing. If you only used Ionic Secure Storage's key-value API (tokens, small settings), the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) is the direct replacement. If you used its SQLite database functionality, migrate to the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) with an `encryptionKey` to keep the same SQLCipher-based encryption. If you also need to gate access behind biometric authentication rather than just encrypting at rest, add the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) on top of either.

### Are these three plugins free, or do they need a paid subscription?

All three plugins (Secure Preferences, SQLite, and Vault) are part of [Capawesome Insiders](https://capawesome.io/insiders/), a paid subscription. There isn't a free-tier equivalent for encrypted storage in the Capawesome catalog; the Insiders subscription is what replaces Ionic Secure Storage's own enterprise licensing.

### Do I need to bundle SQLCipher myself for encrypted SQLite databases?

Yes, on native platforms. Encryption isn't automatic. It requires bundling SQLCipher in your Android and iOS projects, following the platform setup in the plugin's [Encryption](https://capawesome.io/docs/sdks/capacitor/sqlite/#encryption) documentation or the step-by-step [Encrypting SQLite databases in Capacitor](https://capawesome.io/blog/encrypting-capacitor-sqlite-database/index.md) guide. Also don't hard-code the encryption key in your app's source. Store it with the Secure Preferences plugin instead.

### Can I keep using Ionic Secure Storage until 2027?

For now, yes — existing apps keep working, and Ionic has offered active subscribers perpetual, self-support licenses. But the code is effectively frozen: no new features, no compatibility fixes for future Android, iOS, or Capacitor releases. It's safer to migrate before an OS update introduces an incompatibility that can no longer be patched than to wait for the December 31, 2027 end-of-life date.

### Is there a way to migrate stored data automatically, or do I need to re-encrypt everything by hand?

There's no automatic converter between the two plugins' storage formats. For key-value data, the practical approach is reading each value out of Ionic Secure Storage and writing it into Secure Preferences at runtime (similar to the vault-to-vault migration pattern in [Alternative to the Ionic Identity Vault Plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/index.md)), while both dependencies are still installed. For SQLite databases, you're re-creating the schema with `upgradeStatements` and copying rows across, since the two plugins don't share a database file format.

## Need Help Migrating?

If you'd rather not handle the migration yourself, the Capawesome team can take care of it for you. Whether you're dealing with a straightforward key-value store swap or a more complex SQLite setup, we offer dedicated migration services to get you up and running with minimal downtime and effort on your end.

[Book a Free Consultation](https://cal.com/team/capawesome/ionic-appflow-migration)

## Conclusion

Pick the replacement by the Ionic Secure Storage API your app calls. If you used the key-value API, install the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md) and replace the calls one by one. If you used the SQLite API, install the [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md) and pass an `encryptionKey` to `open(...)`; [How to Use SQLite in a Capacitor App](https://capawesome.io/blog/how-to-use-sqlite-in-a-capacitor-app/index.md) covers the full setup, including how to keep the key in secure storage. Add the [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md) if a secret also has to sit behind biometric authentication.

Start while both dependencies can still be installed side by side, because copying the stored data across needs the old and the new plugin at runtime.

**Related reading:**

- [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/index.md)
- [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/index.md)

Have questions about your migration? Join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW) to connect with the community, and subscribe to the [Capawesome newsletter](/newsletter/) to stay updated on the latest news about Capawesome, Capacitor, and the Ionic ecosystem.

If you need help migrating from Ionic Secure Storage or implementing the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/index.md), [Capacitor SQLite plugin](https://capawesome.io/docs/sdks/capacitor/sqlite/index.md), or [Capacitor Vault plugin](https://capawesome.io/docs/sdks/capacitor/vault/index.md), [contact us](mailto:support@capawesome.io).

# A Google Maps Alternative for Capacitor Apps

The most common Capacitor Google Maps alternative is MapLibre, an open-source map renderer that works without a vendor account. Developers usually start looking for one after running into the same three things with `@capacitor/google-maps`: it needs an API key from a project with billing enabled on Android, iOS, and Web, the Android map is drawn behind the WebView, and markers can be added and removed but never updated. This post compares it with the [Capacitor MapLibre plugin](https://capawesome.io/docs/sdks/capacitor/maplibre/index.md) row by row, shows the code, and says where Google Maps is still the better pick.

## Key Takeaways

- `@capacitor/google-maps` requires API keys from an account with billing enabled on Android, iOS, and Web.
- Google Maps Platform replaced the $200 monthly credit with per-SKU free usage caps on March 1, 2025: 10,000 free billable events per month for Essentials, 5,000 for Pro, 1,000 for Enterprise. Maps SDK usage on mobile stayed unlimited.
- On Android, the official plugin renders the map beneath the WebView, so the layers above it have to be transparent.
- `@capacitor/google-maps` offers `addMarker` and `removeMarker`, but no method to update a marker already on the map.
- The Capacitor MapLibre plugin needs no Google billing account and no Google API key, and runs on Android, iOS, and Web.
- Styles and tiles are a separate decision: CARTO, OpenFreeMap and Versatiles work without an account, commercial providers issue their own keys.

## Why developers look for a Capacitor Google Maps alternative

`@capacitor/google-maps` is a solid plugin, and for apps that need Google's map data it is the obvious choice. Three things regularly send teams looking elsewhere: the billing account, the Android rendering model, and the limits of the marker API.

### A billing account is required on every platform

The [official documentation](https://capacitorjs.com/docs/apis/google-maps) is direct about it: *"To use the Google Maps SDK on any platform, API keys associated with an account with billing enabled are required. This is required for all three platforms, Android, iOS, and Javascript."* The Maps SDK for Android [says the same](https://developers.google.com/maps/documentation/android-sdk/usage-and-billing): *"you must enable billing on each of your projects and include an API key or OAuth token with all API or SDK requests."*

That means a card on file before the first map renders, plus three keys to create, restrict, and rotate. On [March 1, 2025](https://developers.google.com/maps/billing-and-pricing/march-2025), Google also replaced the recurring $200 monthly credit with a free usage threshold per SKU. The [current caps](https://developers.google.com/maps/billing-and-pricing/pricing) are 10,000 free billable events per month for Essentials SKUs, 5,000 for Pro, and 1,000 for Enterprise.

To be fair, mobile usage of the Maps SDK is unlimited, so showing a map on a phone does not run up a bill. For most teams the deciding factor is the requirement itself rather than the invoice, especially on open-source apps and client work where nobody wants to own the billing account.

### On Android, the map renders behind the WebView

The docs also spell out the rendering model: *"On Android, the map is rendered beneath the entire webview, and uses this component to manage its positioning during scrolling events. This means that as the developer, you must ensure that the webview is transparent all the way through the layers to the very bottom."*

So you set `background: transparent` on `html`, `body`, `ion-content` and anything else covering the map, then undo it when the user leaves the page. Get it wrong and you see a blank rectangle, which is what happens in [this long-running issue](https://github.com/ionic-team/capacitor-google-maps/issues/69) and in the [dark mode report](https://github.com/ionic-team/capacitor-plugins/issues/1834) where Android's forced dark background paints over the map.

One honest caveat before you switch for this reason alone: the Capacitor MapLibre plugin renders behind the WebView too and needs the same transparent ancestors. Every plugin that draws a real native map view works this way. What differs is the vendor account, not the layering.

### Markers can be added and removed, but not updated

The marker API of `@capacitor/google-maps` consists of `addMarker`, `addMarkers`, `removeMarker` and `removeMarkers`. There is no update method, so moving a marker one meter means removing it, adding a new one, and storing the new ID. On a delivery screen that refreshes every few seconds, that flickers and drops any selection state attached to the marker. It is the core of the issue [Cannot get control of Markers, Circles etc](https://github.com/ionic-team/capacitor/issues/6575).

## What is MapLibre?

MapLibre is an open-source map renderer, forked from Mapbox GL in 2020 after Mapbox moved to a proprietary license. It is BSD-licensed and renders any style that follows the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec/), so it can point at many different tile providers without code changes.

The important split: the renderer is free and open source, the tiles and styles it draws are a separate decision you make yourself. The [Capacitor MapLibre plugin](https://capawesome.io/docs/sdks/capacitor/maplibre/index.md) wraps [MapLibre Native](https://github.com/maplibre/maplibre-native) on Android and iOS and MapLibre GL JS on the Web, giving you one TypeScript API across all three platforms. Setup is described in the [Installation](https://capawesome.io/docs/sdks/capacitor/maplibre/#installation) section of the docs, and the full feature tour is in [Announcing the Capacitor MapLibre Plugin](https://capawesome.io/blog/announcing-the-capacitor-maplibre-plugin/index.md).

## @capacitor/google-maps vs. the Capacitor MapLibre plugin

Here is how the two compare on the features most map screens actually need.

|                                     | `@capacitor/google-maps`                                                                           | Capacitor MapLibre plugin                                      |
| ----------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Google API key + billing account    | Required on Android, iOS, and Web                                                                  | Not required                                                   |
| Platforms                           | Android, iOS, Web                                                                                  | Android, iOS, Web                                              |
| Android/iOS rendering               | Native view behind the WebView, transparent ancestors required                                     | Native view behind the WebView, transparent ancestors required |
| Update a marker in place            | ✗ remove and add again                                                                             | ✓ `updateMarkerById(...)`, including rotation and animation    |
| Marker dragging                     | ✓ all platforms                                                                                    | ✓ Android and Web only                                         |
| Polylines                           | Add and remove                                                                                     | Add, remove, and `updatePolylineById(...)`                     |
| Polygons and circles                | `addPolygons`, `addCircles`                                                                        | GeoJSON source plus `LayerType.Fill` or `LayerType.Circle`     |
| GeoJSON sources and layers          | ✗                                                                                                  | ✓ `addGeoJsonSource(...)` and `addLayer(...)`                  |
| Style switching at runtime          | Map types via `setMapType`, JSON styles set at creation                                            | ✓ `setStyle(...)` with any Style Spec URL or JSON              |
| Marker clustering                   | ✓ `enableClustering()`                                                                             | ✗                                                              |
| Satellite, terrain, traffic, indoor | ✓ built in                                                                                         | Depends on the tile provider you choose                        |
| Offline maps                        | ✗                                                                                                  | ✗                                                              |
| Cost                                | Mobile map loads unlimited, Web under the Essentials free cap, billing account required either way | Plugin is free and open source, tiles depend on the provider   |

Clustering and Google's own data layers are genuine wins for the official plugin, and the MapLibre plugin has no answer to either today. Markers, polylines and GeoJSON go the other way, because the MapLibre API was built around updating objects already on the map instead of replacing them.

## Can I use maps in a Capacitor app without a Google Maps API key?

Yes. The Capacitor MapLibre plugin has no vendor account of its own, so all it needs is a style URL that follows the MapLibre Style Spec. [CARTO basemaps](https://github.com/CartoDB/basemap-styles), [OpenFreeMap](https://openfreemap.org/) and [Versatiles](https://versatiles.org/) serve styles you can point at without registering, while commercial providers such as [MapTiler](https://www.maptiler.com/) hand out their own API keys.

Treat the tile provider as its own decision with its own terms, because rate limits, attribution requirements and acceptable use differ per provider. The plugin's default is the MapLibre demo style, which exists for testing, so set `styleUrl` before you ship.

## Building a map with the Capacitor MapLibre plugin

The API is one flat TypeScript interface, and every method takes the `mapId` of the map it acts on. Here are the pieces of a typical map screen.

### Creating a map

Start with an empty element that defines where the map goes and how large it is.

```
<div id="map"></div>
```

The element must stay empty and must not have a background, because the native map is drawn behind it.

```
#map {
  background: transparent;
  height: 400px;
  width: 100%;
}
```

Then call [`createMap(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#createmap) with an ID for the map, the element to render into, and a style.

```
import { MapLibre } from '@capawesome/capacitor-maplibre';

await MapLibre.createMap({
  center: { latitude: 48.137154, longitude: 11.576124 },
  elementId: 'map',
  mapId: 'my-map',
  styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
  zoom: 12,
});
```

The promise resolves once the style has loaded, so it is safe to add markers right after. On the Web, import `maplibre-gl/dist/maplibre-gl.css` once in your app. Call [`destroyMap(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#destroymap) when the user leaves the screen.

### Adding and updating markers

Markers are added with [`addMarker(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#addmarker) or [`addMarkers(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#addmarkers) and carry their own ID, so there is no handle to keep around.

```
import { MapLibre, MarkerIconAnchor } from '@capawesome/capacitor-maplibre';

await MapLibre.addMarker({
  mapId: 'my-map',
  marker: {
    coordinates: { latitude: 48.137154, longitude: 11.576124 },
    iconAnchor: MarkerIconAnchor.Center,
    iconSize: { height: 32, width: 32 },
    iconUrl: 'https://example.com/marker.png',
    id: 'my-marker',
  },
});
```

This is where the two plugins differ most. [`updateMarkerById(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#updatemarkerbyid) changes only the properties you pass and can animate both the move and the rotation, which is what live vehicle tracking needs.

```
await MapLibre.updateMarkerById({
  animate: true,
  animationDuration: 1000,
  coordinates: { latitude: 48.370545, longitude: 10.89779 },
  mapId: 'my-map',
  markerId: 'my-marker',
  rotation: 90,
});
```

Cleanup works per marker with [`removeMarkerById(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#removemarkerbyid) or in one call with [`removeAllMarkers(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#removeallmarkers).

### Drawing routes with polylines

Routes and recorded tracks are polylines, added with [`addPolyline(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#addpolyline) and styled with `color`, `width` and `opacity`.

```
await MapLibre.addPolyline({
  mapId: 'my-map',
  polyline: {
    color: '#3887be',
    coordinates: [
      { latitude: 48.137154, longitude: 11.576124 },
      { latitude: 52.520008, longitude: 13.404954 },
    ],
    id: 'my-polyline',
    width: 5,
  },
});
```

As the route grows, [`updatePolylineById(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#updatepolylinebyid) replaces the coordinates in place instead of redrawing the line.

### Rendering GeoJSON data

This has no equivalent in `@capacitor/google-maps`. A GeoJSON source holds the data and a layer decides how it is painted, so one source can feed several layers.

```
import { LayerType, MapLibre } from '@capawesome/capacitor-maplibre';

await MapLibre.addGeoJsonSource({
  mapId: 'my-map',
  sourceId: 'my-source',
  url: 'https://example.com/routes.geojson',
});
await MapLibre.addLayer({
  layerId: 'my-layer',
  mapId: 'my-map',
  paint: { lineColor: '#3887be', lineWidth: 4 },
  sourceId: 'my-source',
  type: LayerType.Line,
});
```

[`addGeoJsonSource(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#addgeojsonsource) takes either a `url` or inline `data`, and [`updateGeoJsonSourceById(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#updategeojsonsourcebyid) swaps the data of an existing source when live features arrive over a socket.

### Controlling the camera

[`setCamera(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#setcamera) moves the camera and only touches the properties you pass, including `bearing` and `pitch` for tilted views.

```
await MapLibre.setCamera({
  animate: true,
  bearing: 30,
  center: { latitude: 52.520008, longitude: 13.404954 },
  mapId: 'my-map',
  pitch: 45,
  zoom: 11,
});
```

For search results, [`fitBounds(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#fitbounds) frames a bounding box with optional `padding`, and [`getCamera(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#getcamera) reads the position back.

### Showing the location of the user

Location permissions are handled by the plugin, so you check first and request only when needed.

```
import { MapLibre, UserTrackingMode } from '@capawesome/capacitor-maplibre';

let status = await MapLibre.checkPermissions();
if (status.location === 'prompt') {
  status = await MapLibre.requestPermissions();
}
if (status.location === 'granted') {
  await MapLibre.enableUserLocation({
    mapId: 'my-map',
    trackingMode: UserTrackingMode.Follow,
  });
}
```

`UserTrackingMode.FollowWithCourse` points the camera in the direction the user moves and `FollowWithHeading` follows the compass of the device, the two modes navigation screens usually want.

### Reacting to map events

Events are regular Capacitor listeners, and each carries the `mapId` so a screen with several maps can tell them apart.

```
await MapLibre.addListener('mapClick', event => {
  console.log('Map clicked:', event.coordinates);
});
await MapLibre.addListener('markerClick', event => {
  console.log('Marker clicked:', event.markerId);
});
await MapLibre.addListener('cameraIdle', event => {
  console.log('Camera idle:', event.camera);
});
```

`cameraMoveStarted` reports through `CameraMoveReason` whether the movement came from a gesture or from your own code, which decides when to reload data for the visible area. Drag events and the `draggable` property work on Android and Web only, because markers are rendered as symbol layers on iOS.

### Switching styles at runtime

Since a style is just a URL, dark mode is a style swap rather than a map option.

```
await MapLibre.setStyle({
  mapId: 'my-map',
  url: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
});
```

Keep in mind that [`setStyle(...)`](https://capawesome.io/docs/sdks/capacitor/maplibre/#setstyle) loads a completely new style, so markers, polylines, sources and layers have to be added again afterwards. Running several maps side by side works the same way, since every method is addressed by `mapId`.

## When Google Maps is still the better choice

MapLibre gives you a renderer. Google gives you a renderer plus one of the best map datasets in the world. Pick `@capacitor/google-maps` when you need Street View, POI and Places data, live traffic, indoor floor plans, or satellite and terrain imagery under a single account. Built-in clustering through `enableClustering()` is another concrete advantage, and if your app already calls the Places or Directions APIs, staying inside one platform and one key is less work. If the map itself is the product, Google's data is hard to replace.

## FAQ

### Is the Capacitor MapLibre plugin free?

Yes. The plugin is free and open source, and MapLibre itself is BSD-licensed. The styles and tiles it renders come from a provider you choose, and those carry their own terms and attribution requirements.

### Do I need a Google Cloud billing account?

No. The plugin never talks to Google Maps Platform, so there is no project, no API key and no billing account to set up.

### Does the plugin work on the web?

Yes, through MapLibre GL JS, which ships as a dependency of the plugin. Import `maplibre-gl/dist/maplibre-gl.css` once, otherwise the canvas and the markers end up in the wrong place.

### Does it support offline maps?

No. Styles, fonts, sprites and tiles are loaded over the network, and offline tile management is not part of the plugin today.

### Can I migrate from @capacitor/google-maps without rewriting my UI?

Mostly. The concepts map one to one (map, camera, markers, polylines, events), so your screens and state usually survive. What changes are the method names and the call shape: every MapLibre method is static and takes a `mapId` instead of hanging off a map instance.

## Stay in the loop

New plugins and features land regularly, and the newsletter is the fastest way to hear about them.

[Subscribe to the Capawesome Newsletter](https://capawesome.io/newsletter/)

## Conclusion

The choice comes down to renderer versus data. If your map is a canvas for your own points, routes and areas, the [Capacitor MapLibre plugin](https://capawesome.io/docs/sdks/capacitor/maplibre/index.md) gets you there without a Google Cloud project, and its update methods fit live data better than an add-and-remove API. If you need Street View, Places, traffic or clustering, `@capacitor/google-maps` remains the right tool and the billing account is part of the deal.

For the sensors that pair well with a map screen, [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/index.md) is a good next read. Questions are welcome in the [Capawesome Discord server](https://discord.gg/VCXxSVjefW), and the [Capawesome newsletter](https://capawesome.io/newsletter/) keeps you posted on what ships next.

# An Alternative to Transistorsoft Background Geolocation

If you are searching for a Transistorsoft background geolocation alternative, chances are the license terms triggered the search: since version 9, a paid key is required for release builds on both Android and iOS, priced per app identifier. The [Capacitor Background Geolocation plugin](https://capawesome.io/docs/sdks/capacitor/background-geolocation/index.md) from Capawesome is the most direct alternative. It is also a paid plugin, licensed differently and built with a different engineering philosophy. Transistorsoft invests in motion detection that decides when to track. Capawesome invests in an upload pipeline that makes sure what you tracked reaches your server. This post compares licensing, features and code side by side, including the cases where Transistorsoft remains the better choice.

## Key Takeaways

- Transistorsoft licenses per app identifier: $399 for 1 application key up to $999 for 100 keys, one-time with 1 year of updates. Since v9 (March 2026), release builds require a key on both iOS and Android.
- Polygon geofencing is a separate Transistorsoft add-on starting at $399.
- The Capacitor Background Geolocation plugin is part of Capawesome Insiders: $99/month or $990/year for 30+ Insider SDKs across unlimited apps, or a $1,980 one-time Maintain license with 12 months of updates.
- The core trade-off: Transistorsoft automates when to track with a motion-detection state machine; the Capawesome plugin focuses on reliable delivery with a native SQLite queue, at-least-once upload semantics and a documented server contract.
- Transistorsoft can keep tracking after force-quit and reboot; the Capawesome plugin deliberately ends the watch session and covers relaunch scenarios with the Capacitor Geofences plugin.
- Both plugins support Android and iOS; neither has a web implementation.

## Why teams look for a Transistorsoft background geolocation alternative

The [Transistorsoft plugin](https://github.com/transistorsoft/capacitor-background-geolocation) is a mature commercial product. The same native core has shipped since 2015 for Cordova, React Native, Flutter and Capacitor, releases land in lockstep across all four, and of 319 issues ever opened on the Capacitor repository, only 5 are open today. Teams that go looking for an alternative usually do so for one of four reasons, none of which is "it doesn't work".

### Licensing changed in v9: both platforms now require a key

The Transistorsoft SDK is fully functional in debug builds without a license, so evaluation is free. For release builds, a paid key is required, and this is where v9 changed the rules: earlier versions only enforced the license on Android, while the [9.0.0 release](https://github.com/transistorsoft/capacitor-background-geolocation/blob/master/CHANGELOG.md) from March 2026 requires a key on iOS as well. v9 also switched to a JWT-based key format, so v8 and older keys do not work with it.

[Pricing](https://docs.transistorsoft.com/purchase/) is tiered by the number of application keys: $399 for 1, $599 for 5, $749 for 25 and $999 for 100. Each key unlocks a single app identifier for unlimited users and devices, the purchase is one-time, and it includes 1 year of access to updates. Keys keep working after that year; you stop receiving new releases. Polygon geofencing is a separate add-on that starts at another $399.

None of this is unreasonable for a specialized SDK. It does mean the cost scales with your app portfolio, an agency needs to think about who owns which key, and a major version bump can come with a re-licensing step.

### The setup is extensive

Beyond the usual permission entries that any background location setup needs, the Transistorsoft installation asks for the license key in `Info.plist` and `AndroidManifest.xml`, the `BGTaskSchedulerPermittedIdentifiers` entry, several background modes, custom `variables.gradle` entries and, notably, `shrinkResources false` in the Android release build type, which disables resource shrinking for your whole app. The closed issues reflect that surface: recurring themes are Gradle dependency resolution (for example [issue #2](https://github.com/transistorsoft/capacitor-background-geolocation/issues/2) about resolving `tslocationmanager`) and license validation errors such as [issue #391](https://github.com/transistorsoft/capacitor-background-geolocation/issues/391) after the v9 key format change.

### The native engine is a closed binary

The MIT license in the repository covers the plugin wrapper. The tracking engine itself ships as a prebuilt binary: an xcframework on iOS and a roughly 2.9 MB AAR from Maven Central on Android. You cannot read or patch the code that makes the actual location decisions, which matters to some teams for debugging, auditing or app review questions and doesn't matter at all to others.

### New Capacitor majors take longer to arrive

Measured by npm publish dates, support for a new Capacitor major arrived 7 days after Capacitor 5, 11 days after Capacitor 6, 17 days after Capacitor 7 and 35 days after Capacitor 8. That is a respectable pace for a commercial SDK spanning four frameworks, and the current 9.x line targets Capacitor 8. But if your team upgrades Capacitor early, a five-week wait can block the upgrade of the whole app.

## What is the Capacitor Background Geolocation plugin?

The [Capacitor Background Geolocation plugin](https://capawesome.io/docs/sdks/capacitor/background-geolocation/index.md) is a plugin for reliable background location tracking on Android and iOS, built and maintained by the Capawesome team and introduced in [Announcing the Capacitor Background Geolocation Plugin](https://capawesome.io/blog/announcing-the-capacitor-background-geolocation-plugin/index.md). It is part of [Capawesome Insiders](https://capawesome.io/docs/insiders/index.md), requires Capacitor 8 or later, and is built exclusively on public platform APIs, so there is no binary blob and no behavior that App Review can't reason about.

Its feature set concentrates on the tracking pipeline:

- **Watch sessions** deliver position updates via the [`positionChange`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#addlistenerpositionchange-) event, also while the app is in the background, driven by a correctly plumbed Android 14+ foreground service with a fully configurable notification.
- **A first-class permissions API** handles the two-step background location upgrade flow that both platforms require, including [`openSettings()`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#opensettings) for permanently denied permissions.
- **HTTP upload** sends every queued position to your server without involving JavaScript: buffered in a native SQLite queue, uploaded in batches, retried with exponential backoff and only deleted after the server acknowledges them. Your app can also read the queue directly via [`getQueuedPositions(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#getqueuedpositions), so collecting missed positions doesn't require a server at all.
- **Real tuning knobs** for accuracy, distance filter and update interval, plus [`requestTemporaryFullAccuracy(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#requesttemporaryfullaccuracy) on iOS and automatic pausing via `iosPausesAutomatically`.
- **Mock location detection** on Android: every position reports whether a mock location provider delivered it.
- **A fused-provider escape hatch**: on devices without Google Play services, such as certain Huawei devices, the plugin falls back to the platform location manager, or you force it with `androidForceLocationManager`. Transistorsoft dropped its Huawei HMS support in version 7.2.0 after Google Play rejections.

You can even test the upload pipeline before your backend exists: the free [Background Geolocation Playground](https://background-geolocation-playground.capawesome.io) is a ready-to-use upload target that shows uploaded positions in a table and on a map.

## Transistorsoft vs. the Capacitor Background Geolocation plugin

Here is how the two compare on the axes that decide most projects.

|                                      | Transistorsoft Background Geolocation                                           | Capacitor Background Geolocation plugin                                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| License model                        | One-time per app identifier, $399–$999 for 1–100 keys, 1 year of updates        | [Insiders](https://capawesome.io/docs/insiders/index.md) subscription ($99/month) or one-time Maintain license ($1,980)                    |
| What a license covers                | This plugin for 1–100 app identifiers; polygon geofencing costs extra           | 30+ Insider SDKs across unlimited apps                                                                                                     |
| Platforms                            | Android, iOS                                                                    | Android, iOS                                                                                                                               |
| Capacitor support                    | Capacitor 8 on the current 9.x line, older majors on older lines                | Latest Capacitor, requires Capacitor 8+                                                                                                    |
| Motion-detection auto start/stop     | ✓ accelerometer-driven state machine                                            | ✗ deliberate; explicit tuning knobs instead                                                                                                |
| Tracking after force-quit / reboot   | ✓ `stopOnTerminate: false`, `startOnBoot`, Android headless tasks               | ✗ watch session ends; [Capacitor Geofences plugin](https://capawesome.io/docs/sdks/capacitor/geofences/index.md) covers relaunch scenarios |
| Geofencing                           | ✓ built in, proximity engine beyond the platform limits, polygon as paid add-on | Separate [Capacitor Geofences plugin](https://capawesome.io/docs/sdks/capacitor/geofences/index.md), included in the same subscription     |
| HTTP upload with SQLite queue        | ✓ extensive configuration (auto sync, batch sync, templates)                    | ✓ documented server contract with at-least-once delivery and `id`-based deduplication                                                      |
| Scheduling and odometer              | ✓                                                                               | ✗                                                                                                                                          |
| Devices without Google Play services | Huawei HMS support dropped in 7.2.0                                             | ✓ platform location manager fallback                                                                                                       |
| Native engine                        | Closed-source binary SDK                                                        | Built on public platform APIs                                                                                                              |
| Web support                          | ✗                                                                               | ✗                                                                                                                                          |

The rows are not equally weighted for every app. If your product is a fleet tracker that must record around the clock without the driver ever opening the app, the force-quit row alone can decide it. If your product tracks a delivery during an active shift and your backend must never lose a position, the upload rows matter more.

## The real trade-off: motion intelligence vs. delivery reliability

Transistorsoft's headline feature is a motion-detection state machine. It fuses accelerometer, gyroscope and magnetometer data to decide whether the device is moving, records at the configured distance filter while it is, and turns location services off when the device is stationary. Combined with `stopOnTerminate: false`, `startOnBoot` and headless Android tasks, tracking becomes something you switch on once and stop thinking about, and that engineering is hard to replicate.

The Capawesome plugin takes the opposite stance on purpose. Its [FAQ](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#faq) states that it deliberately does not include a motion-detection state machine that toggles the GPS based on accelerometer data. Instead it gives you explicit control: a lower accuracy, a `distanceFilter`, a longer `androidInterval`, and on iOS the `iosPausesAutomatically` option, which lets the operating system itself pause updates while the device is stationary. The behavior stays predictable, and everything runs on public platform APIs.

Where the Capawesome plugin invests is the delivery side. The queue is a native SQLite database that survives app restarts and force-quits. Positions are uploaded in batches so many positions share a single radio wake-up, retried with exponential backoff, and only removed after your server acknowledges them. Each position carries a strictly increasing `id` per installation, so your endpoint can deduplicate and delivery becomes effectively exactly-once. The response handling is documented status code by status code, and [`getQueueStatus()`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#getqueuestatus), [`triggerUpload()`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#triggerupload) and the [`uploadFailed`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#addlisteneruploadfailed-) event make the queue observable from your app.

So the question is which failure mode costs you more: a battery complaint because tracking ran longer than needed, or a gap in the track because positions were lost between the device and your server.

## Migrating from Transistorsoft

The concepts map well, so a migration is mostly mechanical. The main structural difference is that Transistorsoft is configured once via `ready(config)` and then toggled with `start()` and `stop()`, while the Capawesome plugin splits the configuration in two. The queue and upload are configured once via [`setConfig(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#setconfig) and persisted natively, and each watch session receives its tracking options via `startWatching(...)`.

| Transistorsoft                                   | Capacitor Background Geolocation plugin                                                                                                                                                                                        |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ready(config)` + `start()`                      | [`startWatching(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#startwatching)                                                                                                                        |
| `onLocation(...)`                                | [`positionChange`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#addlistenerpositionchange-) listener                                                                                                      |
| `getCurrentPosition(...)`                        | [`getCurrentPosition(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#getcurrentposition)                                                                                                              |
| `requestPermission()`                            | [`requestPermissions(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#requestpermissions) in two steps                                                                                                 |
| `requestTemporaryFullAccuracy(...)`              | [`requestTemporaryFullAccuracy(...)`](https://capawesome.io/docs/sdks/capacitor/background-geolocation/#requesttemporaryfullaccuracy)                                                                                          |
| `stop()`                                         | [`stop