DEV Community: Robin

Run an On-Device LLM in Your Capacitor App Without an API Key

Robin — Sat, 12 Sep 2026 17:00:53 +0000

Adding an AI feature to a mobile app usually means sending the user's text to a server. You pick a provider, find somewhere for the API key that isn't the app bundle (in practice, a proxy you now run), and accept a bill that grows with every token.

Modern phones offer another route. iOS 26 ships Apple Intelligence behind the Foundation Models framework, and recent Android devices run Gemini Nano through ML Kit and AICore. Both models belong to the operating system, so the prompt, the conversation history and the answer stay on the device. There is no key to protect and no per-request cost.

We built the Capacitor LLM plugin to put one TypeScript API over both. To be upfront, it is our plugin and it ships as part of Capawesome Insiders, a paid subscription. This post condenses the full announcement on our blog.

What On-Device Inference Buys You

Privacy is the headline, but three other things follow from keeping the model on the phone:

No per-token cost. Inference runs on hardware the user already paid for.
Offline generation. Responses come back in airplane mode or with no reception at all.
No app size increase. The model is part of the OS, so the feature adds nothing to your download.

A system model is small next to a frontier model behind an HTTP endpoint, the usable context is roughly 4,000 tokens on both platforms, and the hardware requirements exclude most devices in use today. That fits summarizing a note or rewriting a paragraph, not reasoning across a long document.

One API Over Two System Models

The plugin ships neither a model nor a runtime. It calls each vendor's on-device API and normalizes the result:

Platform	Model	Underlying API	Requirements
Android	Gemini Nano	ML Kit GenAI Prompt via AICore	API level 26+, Gemini Nano-capable device
iOS	Apple Intelligence	Foundation Models	iOS 26+, iPhone 15 Pro or later, Xcode 26 to build
Web	none	none	`getAvailability()` resolves `unavailable`

Two details shape a release plan. Google's ML Kit GenAI Prompt SDK is still in beta, so the plugin pins com.google.mlkit:genai-prompt at 1.0.0-beta2 and lets you override it with the $mlkitGenaiPromptVersion Gradle variable. And Gemini Nano runs on few devices today, roughly the Pixel 9 and Galaxy S25 series, which makes the availability check mandatory.

If you only ship Android, the free Capacitor ML Kit GenAI Prompt plugin wraps the same Google API directly. For the iOS side, our guide on using Apple Intelligence in a Capacitor app walks through the Foundation Models path on a real device, so I won't repeat it here.

Availability Is the First Call You Make

getAvailability() never rejects. On a platform or OS version with no system model it resolves with unavailable, so you can call it at startup and branch on it. Each of the seven statuses maps to a different UI action:

Status	Reported on	What you do
`available`	Android, iOS	Start generating.
`device-not-eligible`	iOS	Fall back to a cloud model.
`downloadable`	Android	Call `downloadModel()`.
`downloading`	Android	Show progress and wait.
`not-enabled`	iOS	Point the user to Settings.
`not-ready`	iOS	Try again later.
`unavailable`	Android, iOS, Web	Hide the feature.

The status changes while your app runs. A user can switch on Apple Intelligence in Settings, or an Android download can finish, and the availabilityChange event covers both cases:

import { Llm } from '@capawesome-team/capacitor-llm';

const watchAvailability = async () =&gt; {
  const { status } = await Llm.getAvailability();
  updateUi(status);
  await Llm.addListener('availabilityChange', event =&gt; {
    updateUi(event.status);
  });
};

Switch over all seven statuses, not the four Android reports or the five iOS reports.

Downloading Gemini Nano on Android

When the status is downloadable, the model has to reach the device first, and Android is the only platform where your app starts it. downloadModel() resolves on completion, and downloadProgress reports a value between 0 and 1. Show that progress, because the download runs long enough that a silent button reads as broken:

import { Llm } from '@capawesome-team/capacitor-llm';

const downloadModel = async () =&gt; {
  await Llm.addListener('downloadProgress', event =&gt; {
    setProgress(event.progress);
  });
  await Llm.downloadModel();
};

Chats Hold the Conversation Context

A chat is the unit of context. createChat(...) returns an identifier you pass to every generation, and optionally takes instructions, the system prompt that shapes the model's role. Pass your own id to map chats onto your data model, or leave it out and get a UUID.

The implementation differs underneath. On iOS each chat is backed by a native language model session. On Android the system API has no multi-turn concept, so the plugin keeps the history in memory and includes it in each prompt. Either way, history does not survive an app restart, and every chat holds native resources until you release it:

import { Llm } from '@capawesome-team/capacitor-llm';

const startChat = async () =&gt; {
  const { id } = await Llm.createChat({
    instructions: 'You are a helpful assistant that answers briefly.',
  });
  return id;
};

const endChat = async (chatId: string) =&gt; {
  await Llm.deleteChat({ id: chatId });
};

deleteChat(...) also cancels an in-flight generation for that chat, so tearing down a chat screen mid-response is safe.

Generating and Streaming Text

There are two ways to get text out. generateText(...) resolves with the complete response and suits short outputs where a spinner is fine. streamText(...) emits chunks through the textChunk event and resolves with the full text at the end. Every event carries the chatId it belongs to, so one listener can serve several chats:

import { Llm } from '@capawesome-team/capacitor-llm';

const streamAnswer = async (chatId: string) =&gt; {
  await Llm.addListener('textChunk', event =&gt; {
    if (event.chatId === chatId) {
      appendToUi(event.text);
    }
  });
  const { text } = await Llm.streamText({
    chatId,
    prompt: 'Summarize this note in three bullet points.',
  });
  return text;
};

Only one generation runs per chat at a time. A second prompt sent into a busy chat rejects with GENERATION_IN_PROGRESS instead of queueing, so disable the send button while a response is in flight.

Canceling a Generation

A small model can spend several seconds on an answer nobody wants any more. cancelGeneration(...) stops the current generation, and the pending promise rejects with GENERATION_CANCELED, a normal outcome rather than an error to report. On iOS it stops immediately. On Android cancellation is best-effort, so a few more textChunk events may arrive afterwards. Track a canceled flag per chat and drop those:

import { Llm } from '@capawesome-team/capacitor-llm';

const canceledChatIds = new Set();

const stopGeneration = async (chatId: string) =&gt; {
  canceledChatIds.add(chatId);
  await Llm.cancelGeneration({ chatId });
};

Where the Platform Limits Bite

Two generation parameters are exposed. maxOutputTokens caps the length of a response and temperature controls how deterministic it is. Both work as chat defaults in createChat(...) and as per-request overrides. The ranges come from the platforms:

Parameter	Android (Gemini Nano)	iOS (Apple Intelligence)
`maxOutputTokens`	Maximum of `4096`.	No documented limit.
`temperature`	Between `0.0` and `1.0`.	Values above `1.0` allowed.
Context size	Input under ~4,000 tokens.	~4,096 tokens per session.

Stay inside the Android ranges if you want one code path across both platforms. The context limit is the one to design around: a long conversation eventually overruns it, the generation rejects with GENERATION_FAILED, and the fix is a new chat seeded with a summary generated while there was still room.

Wrapping Up

Start with getAvailability() and a fallback path, because on most devices today the answer is still unavailable. Once that gate is in place, wire up generateText(...) first, then streamText(...) and cancelGeneration(...) when the UI calls for them.

Every method and error code lives in the plugin documentation, and the longer write-up is in the announcement post. If you have shipped an on-device feature already, tell me in the comments which platform limit you hit first.

The Capacitor AdMob Plugin Built on Google's Next-Gen Ads SDK

Robin — Fri, 11 Sep 2026 17:05:47 +0000

Google runs two Android ad SDKs in parallel right now, and one of them has an expiry date. If you are picking an AdMob library for a Capacitor app this year, that single fact should decide it for you.

We've released the Capacitor AdMob plugin, the first Capacitor AdMob plugin built on Google's Next-Gen Mobile Ads SDK. This is our plugin, and it ships as part of Capawesome Insiders, a paid subscription. Everything below is the short version of the full announcement on our blog.

Why the Next-Gen SDK Matters Now

The legacy Google Mobile Ads SDK on Android sits at major versions 24 and 25 today, and Google has published a deprecation schedule for both. They reach their deprecation date on June 30, 2027 and their sunset date on June 30, 2028. Google's own wording for a sunset version is that ads are "at risk of not serving", with sunset ad requests returning a no fill.

The successor is the GMA Next-Gen SDK. It ships as a new Kotlin-first artifact, com.google.android.libraries.ads.mobile.sdk, with a different API surface instead of another major version of the old library, which is why plugin authors have to port rather than bump a version number.

Our plugin runs on the Next-Gen SDK on Android from its first release, defaulting to ads-mobile-sdk 1.2.1, and on the latest Google Mobile Ads SDK on iOS, where Google has not shipped a Next-Gen variant yet. Both dependency versions are Gradle project variables, so you can pin $adsMobileSdkVersion and $userMessagingPlatformVersion in variables.gradle when another plugin drags in a different version.

Two years sounds like plenty of runway. It is not, if the port lands in the same quarter as a store deadline. Starting a new monetization layer on a library with a published sunset date means paying for it twice.

Five Ad Formats, One Load and Show API

The plugin covers the five AdMob formats Google offers for mobile apps: banner, interstitial, rewarded, rewarded interstitial, and app open. Every full-screen format follows the same two steps, a load method that returns an identifier and a show method that takes it, so learning one teaches you the other three.

Here is a rewarded ad, with the reward listener registered before the ad goes on screen:

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

const showRewardedAd = async () => {
  await Admob.addListener('rewardEarned', ({ amount, type }) => {
    grantReward(amount, type);
  });
  const { id } = await Admob.loadRewardedAd({
    adUnitId: 'ca-app-pub-3940256099942544/5224354917',
  });
  await Admob.showRewardedAd({ id });
};

Swap loadRewardedAd for loadInterstitialAd, loadRewardedInterstitialAd, or loadAppOpenAd and the surrounding code stays the same. Because each load call hands back its own identifier, you can keep several ads in flight at once, say one interstitial preloaded for the end of a level and one rewarded ad sitting behind a "watch for coins" button. Pass your own id if you prefer names you control over generated ones.

Both rewarded formats accept a serverSideVerification option with userId and customData, forwarded to your verification callback so the reward is granted on what Google reports rather than what the client claims. App open ads get a shortcut of their own: enableAppOpenAutoShow(...) loads and shows one whenever the app returns to the foreground, with a minInterval frequency cap that defaults to 14400 seconds, and it stays quiet while a consent form or another full-screen ad is visible.

AdMob is a mobile product, so every method is Android and iOS only and rejects with an unimplemented error on the web.

Banner Ads in Three Modes

Banners are where most Capacitor ad integrations get ugly, because the banner is a native view sitting on top of a web view that knows nothing about it. The plugin gives you three placements, and the right one depends on how much your CSS already knows about the ad.

Mode	What happens	When to use it
`mode: 'overlay'` (default)	Anchored to the top or bottom edge on top of the web view, aware of safe area insets	Your layout already reserves the space, for example a fixed footer
`mode: 'resize'`	The web view shrinks so the banner never covers web content	You want the banner clear of your content without touching your CSS
`frame: { x, y, width, height }`	The banner lands at a rectangle you measure in CSS pixels	Inline placement inside content, for example between list items

Resize mode is the shortest path to a banner that never hides a button, and it needs the ad unit, a size, and a position:

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

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

For inline placement you measure an anchor element with getBoundingClientRect(), pass the rectangle as frame, and call setBannerFrame(...) when the layout shifts. Hold on to the returned identifier, because hideBanner(...), resumeBanner(...), and removeBanner(...) all operate on it, and it is what lets you run more than one banner at a time.

Seven sizes are available. AdaptiveBanner matches the screen or frame width with a height chosen by the SDK, InlineAdaptiveBanner is capped by the frame height you pass, and the fixed sizes cover 320x50, 320x100, 300x250, plus 468x60 and 728x90 for tablets. Set collapsible: true for a banner that expands into a larger ad and collapses back, then listen for bannerSizeChanged to keep your layout honest when it does.

Consent in a Single Call

Google requires User Messaging Platform consent before you request a single ad from users in the European Economic Area, the UK, or a regulated US state. The canonical flow is a request for consent information followed by a conditional form presentation, and requestConsent(...) does both:

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

const setupAds = async () => {
  const { canRequestAds, privacyOptionsRequired } = await Admob.requestConsent();
  if (canRequestAds) {
    await Admob.initialize();
  }
  return privacyOptionsRequired;
};

Call it on every app launch, before initialize(...), because the answer changes over time. Until the consent requirements are met, every load method rejects with CONSENT_NOT_GATHERED, so a non-compliant ad request never leaves the device. When privacyOptionsRequired comes back true, give the user a settings entry that calls showPrivacyOptionsForm(). For the AdMob console setup, the App Tracking Transparency ordering on iOS, and the error cases, we wrote a separate walkthrough on handling AdMob GDPR consent in a Capacitor app.

Impression-Level Revenue for Every Format

Ten events cover the ad lifecycle, most of them carrying the ad's id and format so one listener can serve all five formats. The one to wire up first is adRevenuePaid, because LTV models, ROAS dashboards, and cohort analyses all run on it:

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

const trackAdRevenue = async () => {
  await Admob.addListener('adRevenuePaid', ({ value, currencyCode, precision, format }) => {
    analytics.track('ad_revenue', { value, currencyCode, precision, format });
  });
};

value is the amount in the currency's standard unit, currencyCode is an ISO 4217 code, and precision tells you how much to trust the number: PRECISE, ESTIMATED, PUBLISHER_PROVIDED, or UNKNOWN. Mixing estimated and precise values into one total produces a figure you cannot reconcile against your AdMob reports later.

Should You Switch?

If you are starting an AdMob integration today, start on the Next-Gen SDK. If you already ship ads with @capacitor-community/admob and your setup is one anchored banner plus the occasional interstitial, there is no urgency. Revisit when you need resize or inline banners, several concurrent ad instances, or revenue events across every format. The API mapping is mechanical when you do: prepareInterstitial becomes loadInterstitialAd, prepareRewardVideoAd becomes loadRewardedAd, and adId becomes adUnitId.

The plugin is still marked experimental, so the API surface is complete and typed but has not been through heavy production testing, which makes bug reports genuinely valuable right now.

The plugin documentation has the full API reference, and the announcement post covers the parts I skipped here, including test ad units, typed error codes, and the native setup on both platforms. If you try it, tell me what breaks.

Android Scoped Storage in Capacitor Apps: What Still Works

Robin — Thu, 10 Sep 2026 17:00:33 +0000

Directory.ExternalStorage in @capacitor/filesystem is documented as inaccessible on Android 11 and newer, and no permission brings it back. Code that wrote a PDF into Download/ in 2020 still compiles and fails at runtime on every current device. That is not a plugin bug, it is the storage model Android enforces for every app that targets Android 11 (API level 30) or higher.

This is the condensed version of our longer write-up, Android Scoped Storage in Capacitor Apps, Explained. One disclosure first. The Capacitor File Manager plugin in the code samples is ours, and it is part of Capawesome Insiders, a paid subscription. The Android behavior below applies either way.

What Android changed, and when

Scoped storage limits an app to its own directory on external storage plus the media files it created itself. Android made it the default for apps that target Android 10 (API level 29) and higher, so an app can no longer walk the shared volume and read whatever it finds there.

Android 10 still allowed an opt-out. An app could set android:requestLegacyExternalStorage="true" in its manifest and keep the old behavior. Android 11 (API level 30) ignores that flag as soon as your app targets Android 11, and the same page states that both WRITE_EXTERNAL_STORAGE and the privileged WRITE_MEDIA_STORAGE permission stop providing additional access at that target level.

You cannot sit this out. Since 31 August 2026, Google Play requires new apps and app updates to target Android 16 (API level 36) or higher, six releases past the point where the legacy flag became dead configuration.

The Download directory is the one everybody asks about. Android 11 removed it from what the Storage Access Framework hands out. The system picker still lists it, but Google's own test instructions describe the expected result as the directory showing up with "the action button associated with the directory grayed out". The internal storage root and the roots of reliable SD card volumes are blocked the same way. For a file that has to land there, use the MediaStore.Downloads collection instead.

What still works in @capacitor/filesystem

Most of the plugin is unaffected. Scoped storage restricts shared storage, not the app sandbox, so app-specific directories behave as before Android 10 and need no permission.

Directory	Status on Android 11 and newer
`Directory.Data`	Works. Maps to `getFilesDir()`, private to the app.
`Directory.Cache`	Works. Maps to `getCacheDir()`, may be reclaimed by the system.
`Directory.Library`	Works. Maps to `getFilesDir()` on Android.
`Directory.External`	Works. App-specific directory on the shared volume.
`Directory.ExternalCache`	Works. App-specific cache on the shared volume.
`Directory.Documents`	Partly. Your app only sees files and folders it created itself.
`Directory.ExternalStorage`	Gone. Documented as not accessible on Android 11 or newer.

Two issues in ionic-team/capacitor-filesystem have tracked this gap for years without a resolution. #28, asking the plugin to accommodate scoped storage, was opened on 30 December 2020. #37 asks which Directory member to use for which purpose now that half the enum behaves differently per Android version. Until one of them lands, treat @capacitor/filesystem as a sandbox API that stops at the boundary of shared storage.

Why MANAGE_EXTERNAL_STORAGE is the wrong fix

MANAGE_EXTERNAL_STORAGE is the "all files access" permission Android 11 introduced, and it does restore broad access to shared storage. It is also the declaration most likely to stall a Play Store review. Google Play has evaluated apps that declare it under a dedicated policy since May 2021, and Google's guidance is to request it only when the app cannot do its job through the Storage Access Framework or the MediaStore API.

The permitted uses are narrow and tied to core functionality. File managers, backup tools, anti-virus apps, and similar categories where browsing arbitrary files is the product. An expense app that drops receipts into a folder is not in that group, and reviewers treat document management as a use case the Storage Access Framework already covers. The permission does not widen the Storage Access Framework either, so it buys you nothing there.

How the Storage Access Framework replaces shared paths

The Storage Access Framework turns "give me a path" into "let the user grant me a folder". Your app fires an ACTION_OPEN_DOCUMENT_TREE intent, available since Android 5.0 (API level 21), and the user picks a directory in the system picker. What comes back is a tree URI covering that directory and everything beneath it, and nothing else.

That grant expires when the device restarts. Calling takePersistableUriPermission() with the read and write flags makes it survive reboots and app restarts, which turns a one-off picker result into a folder your app keeps using. Android drops it again if the document behind it is moved or deleted, and the user then has to pick a folder again.

Nothing in this flow needs a permission in your manifest. The user's choice in the system picker is the permission.

Persisting a folder with the File Manager plugin

The Capacitor File Manager plugin puts that flow behind two methods, so you never touch a tree URI or a permission flag yourself. Let the user pick a directory with pickDirectory() from the Capacitor File Picker plugin, then pass the result to persistDirectoryAccess(...).

import { FileManager } from '@capawesome-team/capacitor-file-manager';
import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickExportFolder = async () => {
  const result = await FilePicker.pickDirectory();
  const { directory } = await FileManager.persistDirectoryAccess({
    uri: result.path,
    bookmark: result.bookmark,
  });
  return directory;
};

The bookmark value is the iOS half of the same idea, a security-scoped bookmark. Android ignores it, because the persisted tree URI already carries the grant.

Do not store the returned URI yourself, because it can change between app launches. Read the current list on startup with getPersistedDirectories() instead, which drops directories whose document no longer exists. Every method of the plugin accepts a persisted URI. Build the URI of a file inside the folder with getUri(...) by passing parentUri instead of directory, then copy, move or read as usual.

import { Directory, FileManager } from '@capawesome-team/capacitor-file-manager';

const exportReport = async (directoryUri: string) => {
  const { uri: sourceUri } = await FileManager.getUri({
    path: 'report.pdf',
    directory: Directory.Cache,
  });
  const { uri: targetUri } = await FileManager.getUri({
    path: 'exports/report.pdf',
    parentUri: directoryUri,
  });
  const { uri } = await FileManager.copyFile({ uri: sourceUri, toUri: targetUri });
  return uri;
};

Two things to watch. Constructing the URI of an entry that does not exist yet works only for path-structured document providers such as local device storage, so a cloud provider mounted into the picker may reject it. And copyFile(...) returns the URI of the created file, which differs from the one you requested if the provider renamed the file to avoid a collision.

Which directory or API should you use?

Pick by who owns the file and who needs to see it, not by which directory name sounds closest to the old one.

What you need	What to use
App data that must survive updates and stay private	`Directory.Data`
Files you can regenerate at any time	`Directory.Cache`
Large app-owned files on the shared volume	`Directory.External`
A user-visible folder your app keeps using across launches	`pickDirectory()` plus `persistDirectoryAccess(...)`
A single file the user selects once	`pickFiles(...)` from the File Picker plugin
Photos, videos or audio in the gallery	MediaStore collections (platform API)
A download the user finds in `Download/`	The `MediaStore.Downloads` collection
Browsing arbitrary files across the device	`MANAGE_EXTERNAL_STORAGE`, only as core functionality

Conclusion

If your app writes outside its own sandbox on Android, stop hunting for a directory constant that still works. Grep the project for Directory.ExternalStorage and Directory.Documents, move those call sites to a picked and persisted directory, and keep Directory.Data and Directory.Cache for everything the user never has to see. That split holds for every Android version you still support, so you do the work once.

The full guide goes deeper on the permission history, and our Capacitor file handling guide covers reading, writing and sharing files without running out of memory. If your case does not fit a row of the table above, drop it in the comments.

Apple Intelligence in a Capacitor App: On-Device Text Generation

Robin — Wed, 09 Sep 2026 17:00:52 +0000

Sending user text to a hosted language model costs money on every request, adds latency, and means notes and messages leave the phone. Since iOS 26, Apple's Foundation Models framework opens the on-device model behind Writing Tools to third-party apps, so a summarize button can run offline, for free, with no API key to rotate. Here is how to reach that model from a Capacitor app without writing Swift.

Full disclosure: the Capacitor LLM plugin used throughout this post is ours, and it is part of Capawesome Insiders, a paid subscription. You need a license key to install it from the Capawesome npm registry. Apple's model itself costs nothing per request. This is the condensed version of How to Use Apple Intelligence in a Capacitor App from our blog.

What the plugin exposes

The plugin wraps the Foundation Models framework in one TypeScript API. From your web code you get chat sessions that keep conversation context and carry instructions, token streaming through an event, cancellation of a running generation, a typed availability status, and per-chat or per-request temperature and maxOutputTokens.

Two things Apple's framework offers are not exposed yet: guided generation into typed structures and tool calling. Plan for free-text responses.

Inference runs on the Neural Engine. The plugin bundles no model files, makes no network calls, and adds no data type to your privacy nutrition label. It calls only public platform APIs, so there is nothing extra to explain to App Review.

What you need

Hardware alone does not decide whether the model runs. Four other conditions have to hold as well:

Requirement	Detail
Device	iPhone 15 Pro or later, iPad mini (A17 Pro) or M1 iPads and later, Apple silicon Macs, Apple Vision Pro. Apple keeps the current list on its Apple Intelligence support page.
OS version	iOS 26, iPadOS 26, macOS 26, or visionOS 26. Apple Intelligence shipped with iOS 18.1, but the developer API did not.
Apple Intelligence turned on	The user enables it under Settings > Apple Intelligence & Siri. Until then the plugin reports `not-enabled`.
Storage	About 7 GB of free space for the model download, which the system manages.
Build toolchain	Xcode 26 or later, plus Capacitor 8 for the plugin itself.

On iOS 18 every method except getAvailability() rejects as unavailable. On an iPhone 15 or older, the status is device-not-eligible. Both are normal states your UI has to handle, which is where the first step comes in.

Step 1: Check availability before showing the feature

getAvailability() never rejects. On iOS it resolves with one of five statuses, and each one maps to a different UI decision:

Status	Meaning	What to do
`available`	The model is ready.	Enable the feature.
`device-not-eligible`	The hardware cannot run Apple Intelligence.	Hide the feature or fall back to a server.
`not-enabled`	Apple Intelligence is off in Settings.	Explain how to turn it on, then check again.
`not-ready`	The system is preparing or downloading the model.	Show a waiting state.
`unavailable`	No system model on this OS version.	Hide the feature or fall back to a server.

A small helper turns the status into something a component can render:

import { Llm } from '@capawesome-team/capacitor-llm';

const checkAppleIntelligence = async () => {
  const { status } = await Llm.getAvailability();
  switch (status) {
    case 'available':
      return { enabled: true };
    case 'not-enabled':
      return { enabled: false, hint: 'Turn on Apple Intelligence in Settings to use this feature.' };
    case 'not-ready':
      return { enabled: false, hint: 'The on-device model is still being prepared. Try again in a moment.' };
    default:
      return { enabled: false };
  }
};

The status changes while your app is open, for example when the user enables Apple Intelligence in Settings and switches back. Listen for the availabilityChange event and re-run the check when it fires:

import { Llm } from '@capawesome-team/capacitor-llm';

const watchAvailability = async (onChange: (status: string) => void) => {
  return Llm.addListener('availabilityChange', (event) => {
    onChange(event.status);
  });
};

The plugin watches the system status only while a listener is attached, so remove it when the screen goes away.

Step 2: Create a chat with instructions

Every generation belongs to a chat. On iOS a chat is backed by a native model session that keeps the conversation context, so a follow-up prompt can refer to the previous answer. Pass instructions to define the role and the output format:

import { Llm } from '@capawesome-team/capacitor-llm';

const createSummaryChat = async () => {
  const { id } = await Llm.createChat({
    instructions:
      'You summarize notes into at most three short bullet points. Keep the language of the note.',
  });
  return id;
};

The id is optional, and passing your own (one per document, say) makes a second createChat(...) with the same id reject with CHAT_ALREADY_EXISTS. Chats live in memory and each one holds a native session, so delete a chat when the user leaves the screen with Llm.deleteChat({ id }). Deleting also cancels a generation still running in that chat.

Step 3: Generate a response

generateText(...) sends a prompt into a chat and resolves with the complete response:

import { Llm } from '@capawesome-team/capacitor-llm';

const summarize = async (chatId: string, note: string) => {
  const { text } = await Llm.generateText({
    chatId,
    prompt: `Summarize this note:\n\n${note}`,
  });
  return text;
};

One generation runs per chat at a time. Starting a second before the first resolves rejects with GENERATION_IN_PROGRESS, so disable the submit button while a request is pending, or give each task its own chat.

Step 4: Stream tokens into the UI

For anything longer than a sentence, waiting for the full response feels broken. streamText(...) emits a textChunk event for every piece and still resolves with the complete text at the end. Filter by chatId, because chunks from all chats arrive through the same listener:

import { Llm } from '@capawesome-team/capacitor-llm';

const streamSummary = async (chatId: string, note: string, onUpdate: (text: string) => void) => {
  let output = '';
  const listener = await Llm.addListener('textChunk', (event) => {
    if (event.chatId === chatId) {
      output += event.text;
      onUpdate(output);
    }
  });
  try {
    const { text } = await Llm.streamText({
      chatId,
      prompt: `Summarize this note:\n\n${note}`,
    });
    return text;
  } finally {
    await listener.remove();
  }
};

Append the chunks in arrival order. The resolved text equals the concatenated chunks, so use whichever fits your rendering.

Step 5: Cancel a generation

A user who can watch a response arrive will want to stop it. cancelGeneration(...) stops the running generation of a chat, and the pending promise rejects with GENERATION_CANCELED, which you should treat as a normal outcome rather than an error:

import { Llm } from '@capawesome-team/capacitor-llm';

const stop = async (chatId: string) => {
  await Llm.cancelGeneration({ chatId });
};

const summarizeWithCancel = async (chatId: string, note: string) => {
  try {
    const { text } = await Llm.generateText({ chatId, prompt: note });
    return text;
  } catch (error) {
    if ((error as { code?: string }).code === 'GENERATION_CANCELED') {
      return null;
    }
    throw error;
  }
};

On iOS the cancellation takes effect immediately, and the chat stays usable afterwards.

Limits to plan for

Two parameters shape the output. temperature controls how deterministic it is, maxOutputTokens caps its length, and both can be set per chat and overridden per request. Their ranges differ by platform:

Parameter	iOS (Apple Intelligence)	Android (Gemini Nano)
`temperature`	Values above `1.0` are allowed.	Between `0.0` and `1.0`.
`maxOutputTokens`	No documented hard limit.	At most `4096`.
Context size	About 4,096 tokens per chat session.	Input under about 4,000 tokens.

The context window is the limit you hit first. Instructions, every prompt, and every response count against it, and once it overflows the next generation rejects with GENERATION_FAILED. The same code appears when Apple's guardrails block a prompt or a response, so read the error message for the platform reason and show the user something better than a silent failure. For a summarizer, one chat per document keeps the window from filling up.

The same code runs on Android

The plugin uses Gemini Nano through the ML Kit GenAI Prompt API on Android, so the create, generate, stream, and cancel calls above need no changes. Availability differs: Android reports available, downloadable, downloading, and unavailable, and on downloadable your app triggers the download itself. Chat history is kept in memory by the plugin, because the Android API has no native multi-turn sessions, and cancellation is best-effort, so a few extra chunks can still arrive.

Wrapping up

Gate the feature on getAvailability(), ship generateText(...) first, then add streaming and a cancel button together once responses grow past a sentence. Keep one chat per task and the 4,096-token window stays out of your way.

The API reference for every method and event is in the Capacitor LLM plugin documentation, and the long-form walkthrough with the full note summarizer class, an availability troubleshooting table, and Simulator notes is in How to Use Apple Intelligence in a Capacitor App. If you build something with the on-device model, I would like to read about it in the comments.

Ionic Framework MCP Server for Your AI Assistant

Robin — Tue, 08 Sep 2026 15:04:50 +0000

Ask your AI assistant which events ion-modal emits and get the v9 answer, with a usage example for your framework. The Ionic Framework MCP server gives the assistant the current documentation for v9 and v8, including the component API reference and the official usage examples for Angular, React, Vue and vanilla JavaScript, instead of whatever was in its training data a release or two ago. It is a community project built and hosted by Capawesome, not an official Ionic product, and it is free to use with no account and no token.

A short screen recording on the original post shows Claude Code listing Ionic Framework components through the server.

Key takeaways:

The Ionic Framework MCP server runs at https://ionic-framework-mcp.capawesome.io/mcp. No account, no token, no installation.
It serves the Ionic Framework documentation for v9 and v8, the component API reference, the official usage examples for Angular, React, Vue and vanilla JavaScript, and the Ionic blog.
Five tools: search_docs, get_doc_page, list_components, get_component_usage and list_blog_posts.
A version parameter pins every answer to the major version your project installs. It defaults to v9.

Why assistants get it wrong

Because a model answers from a snapshot of the web, and your project is not on that snapshot. Ionic Framework v9 landed after most training sets were assembled, so an assistant that learned v8 writes v8 property names, v8 event names, and v8 CSS custom properties, and nothing fails loudly. A ::part() selector aimed at a shadow part that the release does not have still compiles and renders, and changes nothing.

Component APIs are where this hurts most. ion-datetime alone carries dozens of properties, several events, and a list of CSS shadow parts that moves between major versions. No model holds those tables accurately for two releases at once, and it has no way to know which release you installed.

With the MCP server connected, the assistant fetches the page it needs on its own and answers from it, without you pasting documentation into the chat or your agent parsing HTML from a web fetch.

What the server provides

The server exposes five tools, and the assistant decides on its own which one a question needs:

Tool	Description
`search_docs`	Search the documentation by keyword.
`get_doc_page`	Fetch a full documentation page as Markdown.
`list_components`	List Ionic Framework components with their API reference.
`get_component_usage`	Read the official usage examples for a component, per framework.
`list_blog_posts`	List recent posts from the Ionic blog.

Ask "Which events does ion-modal emit?" and the assistant calls search_docs, then get_doc_page on the modal page. Back comes the v9 event table, ionModalDidPresent and ionModalDidDismiss included, with the exact names instead of plausible ones.

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 the table an assistant needs to style a component correctly instead of inventing a selector that looks plausible.

get_component_usage returns the official usage examples from the documentation and takes a framework of angular, react, vue or javascript. An Angular project gets the Angular template, not a React snippet the model translated on the fly. list_blog_posts covers the Ionic blog, so release notes and announcements are in reach as well.

Version-aware answers

Every documentation tool accepts a version parameter, with v9 as the default and v8 as the alternative. Set it to the major version of @ionic/core, @ionic/angular, @ionic/react or @ionic/vue in your package.json, so the properties and events your assistant suggests exist in the release you ship.

Put a line in your AGENTS.md or CLAUDE.md so the assistant sets it without being asked every time:

When using the Ionic Framework MCP server, always pass the `version`
parameter that matches the major version installed in package.json.

Setup

It is a remote HTTP server, so most clients need one line. In Claude Code:

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

Cursor, VS Code, Claude Desktop, Windsurf and Zed each want their own config file, and clients that cannot speak HTTP can run npx -y @capawesome/ionic-framework-mcp as a stdio proxy to the hosted server. The Ionic Framework MCP server documentation has the exact snippet for each. Once connected, ask your assistant something like "Show me an inline ion-datetime in React" to check that the tools are available.

How it works

The server runs as a Cloudflare Worker in front of a search index that is rebuilt daily from ionic-team/ionic-docs at a pinned commit, with the source MDX converted to Markdown so pages arrive as text a model can read instead of a mix of JSX components. A daily rebuild means a documentation change reaches your assistant the next day without you touching anything. The client package is open source at capawesome-team/ionic-framework-mcp, and its issue tracker is the place to report a wrong search result or a missing parameter.

Unofficial, with attribution

The server is maintained by Capawesome. It is not affiliated with or endorsed by Ionic or OutSystems, and its documentation page says so at the top.

The documentation content is © the Ionic team and licensed under Apache-2.0. It comes from ionic-team/ionic-docs, converted from MDX to Markdown for delivery over MCP and otherwise served unmodified in substance. Blog excerpts come from the Ionic blog and link to the original post.

Capacitor

Most Ionic Framework apps ship on Capacitor, and the same version problem applies there. The Ionic team is working on an official Capacitor MCP server, discussed in ionic-team/capacitor#8555. That discussion is the place to say what it should cover.

Until it arrives, our Capacitor MCP server serves the Capacitor documentation on the same terms: free, no token, a version parameter, a daily rebuild. It is a stopgap so the community has something to point an assistant at today, and its documentation page will link the official server once that ships.

Final Thoughts

Add the server to the assistant you already use, then pin the version parameter in your project rules and leave it there. One command removes a class of wrong answers, the ones that look right because they were right in the previous major.

If you also ship with Capawesome, add the Capawesome MCP server next; it covers the Capawesome plugins and Capawesome Cloud, and with an API token it can act on your apps rather than only read documentation. For the wider picture of agent-driven development, read How to Use AI Agents in Capacitor App Development. Questions and bug reports are welcome on the Capawesome Discord server, and the Capawesome newsletter is where the next server gets announced.

Originally published at capawesome.io.

Scan Documents in Capacitor with ML Kit and VisionKit

Robin — Fri, 04 Sep 2026 17:04:18 +0000

Document scanning UI is a solved problem: Google and Apple each ship a polished, ML-powered scanner with the operating system — the same flows users know from Google Drive and Apple Notes. What a Capacitor app needed was a bridge, not another camera stack. We just released the Capacitor Document Scanner plugin, and its surface is deliberately tiny.

Two API calls

Check availability, then scan:

import { DocumentScanner } from '@capawesome-team/capacitor-document-scanner';

const { available } = await DocumentScanner.isAvailable();

const { scannedImages } = await DocumentScanner.scanDocument({
  imageQuality: 80,
  pageLimit: 5,
});

The OS detects the edges, corrects the perspective, and offers a review step before the pages come back as JPEG files in the cache directory. A user backing out is a normal outcome: the promise rejects with SCAN_CANCELED.

Get a PDF instead of loose images

const { pdf } = await DocumentScanner.scanDocument({
  generatePdf: true,
});

One combined PDF of all scanned pages — generated by ML Kit on Android, composed from the page images on iOS. Perfect for receipts, signed contracts, and anything a backend expects as a single file.

Platform behavior, documented honestly

On Android, androidScannerMode selects the editing capabilities (Base for crop/rotate, BaseWithFilter adds filters, Full adds ML-based cleaning that removes stains, fingers, and shadows), and androidGalleryImportAllowed lets users import an existing photo. iOS applies its cleaning automatically and keeps its UI fixed.
pageLimit is enforced by the scanner on Android; on iOS it truncates the result after scanning, because VisionKit exposes no public stop API — and using a private one would risk App Review.
The Android scanner ships as an on-demand Google Play services module, downloaded on first use, so it adds nothing to your app size.
Files land in the cache directory with automatic stale-file cleanup — copy anything you want to keep.

The plugin is built exclusively on public platform APIs, is part of Capawesome Insiders, and requires Capacitor 8+. The full announcement covers the availability check semantics and the companion plugins for viewing, printing, and sharing the results.

Background Geolocation in Capacitor Without Losing Positions

Robin — Thu, 03 Sep 2026 17:03:42 +0000

Most background location setups in Capacitor apps share a silent failure mode: positions are collected in JavaScript, and JavaScript stops the moment the operating system suspends the web view. The result is a track with holes, discovered in production. We just released the Capacitor Background Geolocation plugin to fix exactly that: every position is recorded natively into an SQLite queue and uploaded to your server, whether or not the web view is awake.

Permissions the way the platforms actually work

Neither platform lets you ask for foreground and background location in one prompt, so the plugin doesn't pretend otherwise:

import { BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

let status = await BackgroundGeolocation.requestPermissions({
  permissions: ['location', 'notifications'],
});
if (status.location === 'granted') {
  status = await BackgroundGeolocation.requestPermissions({
    permissions: ['backgroundLocation'],
  });
}

Watch sessions with real tuning knobs

import { Accuracy, BackgroundGeolocation } from '@capawesome-team/capacitor-background-geolocation';

await BackgroundGeolocation.startWatching({
  accuracy: Accuracy.High,
  distanceFilter: 10,
  androidNotification: {
    title: 'Location Tracking',
    text: 'Your location is being tracked.',
  },
});

androidNotification is mandatory because Android requires a foreground service with a persistent notification — the plugin makes that explicit instead of inventing one. There's deliberately no accelerometer-driven motion-detection state machine; battery is controlled through predictable knobs (accuracy, distanceFilter, androidInterval, iosPausesAutomatically).

The queue is the source of truth

Enable it once and every position is written natively:

await BackgroundGeolocation.setConfig({ maxSize: 50000 });

The positionChange event becomes what it honestly is — a live feed for your UI — while the queue survives restarts and force-quits. Drain it with getQueuedPositions(...) and acknowledge with deleteQueuedPositions({ upToId }); ids are strictly increasing, so a crash between reading and persisting never loses a position.

Upload without JavaScript

Add a url and the queue uploads itself in batches:

await BackgroundGeolocation.setConfig({
  url: 'https://api.example.com/positions',
  batchSize: 100,
  flushInterval: 60000,
  headers: { Authorization: 'Bearer ...' },
});

Delivery is at least once with a documented status-code contract: 2xx acknowledges, 401/408/429/5xx retry with exponential backoff, anything else drops the batch permanently so it can't block the queue. Deduplicate by position id on the server and delivery is effectively exactly-once. You can test the whole pipeline against the free Background Geolocation Playground before your endpoint exists.

One honest limit: a force-quit ends the watch session — that's an OS restriction. Queued positions survive and upload on the next start, and OS-managed geofencing (a separate plugin) covers relaunch scenarios.

The plugin is part of Capawesome Insiders and requires Capacitor 8+. The full announcement covers the complete server contract and the battery trade-offs.

Fixing the Invisible Camera Preview in Capacitor Barcode Scanners

Robin — Wed, 02 Sep 2026 17:00:55 +0000

Search any Capacitor forum for barcode scanning and one bug dominates: the camera preview is invisible. The classic approach renders the camera behind the web view and requires your entire app to be transparent — which works until an Ionic modal, a page transition, or a dark theme paints a background over it.

We took a different route with the embedded mode of the Capacitor Barcode Scanner plugin: the camera preview is a native view positioned inside your app layout, above the web view, so HTML can never cover it by accident.

Position the camera with a placeholder element

Your markup reserves the space, and the element's bounding rectangle becomes 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 };
};

await BarcodeScanner.addListener('barcodesScanned', (event) => {
  console.log('Scanned barcodes:', event.barcodes);
});
await BarcodeScanner.startScan({
  frame: getScanFrame(),
  lensFacing: LensFacing.Back,
});

Detected barcodes stream in continuously until stopScan(). A duplicateTimeout (default 1500 ms) prevents the same barcode from flooding your handler, formats restricts detection to what you expect, and detectionArea limits detection to a region within the frame.

Keep the frame in sync

The native view doesn't reflow with your CSS, so update it when the layout changes:

window.addEventListener('resize', async () => {
  await BarcodeScanner.setScanFrame({ frame: getScanFrame() });
});

Overlays are an explicit opt-in

If your design needs HTML drawn over the camera (a viewfinder, detection markers), set placement: PreviewPlacement.Behind and the preview renders behind the web view. That mode has the same transparency requirement as the classic approach — but now it's a scoped choice for one screen you design around, not a global precondition for scanning at all.

It works on the web, too

The embedded mode and readBarcodesFromImage(...) are supported on the web via the BarcodeDetector API (with a recommended polyfill for browsers without it). Torch, zoom, and the ready-made fullscreen scanner are native-only.

The full guide also covers torch and zoom control, camera selection, the themeable fullscreen scanner, and migrating from the ML Kit Barcode Scanning plugin.

Announcing the Capacitor MapLibre Plugin

Robin — Fri, 28 Aug 2026 14:00:56 +0000

Showing a native map in a Capacitor app has practically meant one thing: Google Maps, plus the billing account it requires before the first tile loads. We just released the Capacitor MapLibre plugin, the first native MapLibre integration for Capacitor — free, open stack, and no vendor account required by the plugin.

It renders maps with the native MapLibre SDKs on Android and iOS and with MapLibre GL JS on the Web, so one TypeScript API covers all three platforms.

How the Native Rendering Works

On Android and iOS, the map is a native view rendered behind the web view, positioned by an empty element in your DOM. The contract is small: the map element stays empty, and it and every ancestor covering the map region use background: transparent — otherwise the web view paints over the map.

The upside of this architecture: any DOM element that isn't an ancestor of the map element renders above the map. Floating action buttons, bottom sheets, and dialogs just work. The plugin also keeps the native view in sync with the element's position and size automatically, including while the page scrolls.

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,
  });
};

Every method takes the mapId, so multiple maps can run at the same time.

Markers with Animated Updates

Markers take custom icons with configurable anchor, size, and rotation, and can be moved with a smooth animation — the building block for live vehicle tracking:

import { MapLibre, MarkerIconAnchor } from '@capawesome/capacitor-maplibre';

const addAndMoveMarker = 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',
    },
  });
  await MapLibre.updateMarkerById({
    animate: true,
    animationDuration: 1000,
    coordinates: { latitude: 48.370545, longitude: 10.89779 },
    mapId: 'my-map',
    markerId: 'my-marker',
    rotation: 90,
  });
};

GeoJSON Layers

For routes, areas, and anything your backend already stores as GeoJSON, add a source and style it with line, fill, or circle layers:

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,
  });
};

User Location

Request the location permission, then display and follow 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,
  });
};

Map Styles and API Keys

The plugin renders any style following the MapLibre Style Spec. "No API key required by the plugin" is not the same claim as "free tiles": the style decides where tiles come from. Free providers such as OpenFreeMap and CARTO basemaps exist, while commercial providers such as MapTiler use their own keys. Follow your provider's attribution requirements, and don't ship the default demo style — it's for testing only.

Availability

The plugin is free, requires Capacitor 8 or later, and one known limitation applies: offline tile management is not part of this version. The full announcement is on our blog: Announcing the Capacitor MapLibre Plugin, and the plugin documentation covers the complete API.

Questions or feedback? Drop a comment — happy to answer.

Announcing the Capacitor File Transfer Plugin

Robin — Thu, 27 Aug 2026 14:00:49 +0000

If you've ever shipped a download feature in a Capacitor app, you know the failure modes: the user switches apps halfway through a 500 MB file, the operating system kills the process, or a big transfer quietly eats someone's mobile data plan. The official @capacitor/file-transfer plugin covers foreground transfers; we just released the Capacitor File Transfer plugin to handle everything around them.

Transfers as Tasks

The core idea: a transfer is a first-class, persisted object. Starting one returns an identifier immediately, the work runs in native code that outlives your web view (a background URLSession on iOS, a dataSync foreground service on Android), and the state can be queried later — even after an app restart.

Start a Download

import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const startDownload = async () =&gt; {
  const { id } = await FileTransfer.startDownload({
    url: 'https://example.com/file.zip',
    path: '/path/to/destination/file.zip',
    headers: {
      Authorization: 'Bearer ',
    },
    network: 'unmetered',
    maxRetries: 3,
    androidNotification: {
      title: 'Downloading file',
      text: 'The file is being downloaded.',
    },
  });
  return id;
};

network: 'unmetered' keeps the download off mobile data, and maxRetries retries with backoff on network errors instead of failing on the first dropped packet.

Uploads, Including S3 Presigned URLs

Uploads send multipart/form-data by default and switch to a raw binary body for presigned URLs:

import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const uploadToPresignedUrl = async () =&gt; {
  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;
};

The file streams straight from the file system into the request — no base64 detour, no blob in JavaScript memory.

Events That Survive Backgrounding

Transfers report their state through transferProgress, transferCompleted, and transferFailed events. The important detail: completed and failed events that occur while no listener is registered are retained and delivered as soon as a listener is added, so a download that finishes while your app is in the background still reaches your code on the next launch.

Pause, Resume, Restore

Downloads can be paused and resumed at any time — even after the process was killed, via resume data on iOS and HTTP Range requests on Android. And because transfers are persisted, getTransfers() rebuilds a download manager UI after a restart:

import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';

const restoreTransferList = async () =&gt; {
  const { transfers } = await FileTransfer.getTransfers();
  return transfers.filter(transfer =&gt; transfer.state === 'running' || transfer.state === 'paused');
};

Uploads cannot be paused: plain HTTP uploads have no standard resume mechanism, so the plugin rejects instead of faking a pause that would restart from zero anyway.

What Happens in Each App State

Instead of leaving it to experimentation, the behavior is documented per platform:

App state	Android	iOS
Foreground	Runs.	Runs.
Backgrounded	Runs in the `dataSync` foreground service.	Runs in the background `URLSession`.
Killed by the OS	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 iOS behavior).

Resuming an interrupted download requires the server to support the HTTP Range header.

Migrating from @capacitor/file-transfer

The switch is mostly a rename plus a change of model — transfers become asynchronous tasks:

`@capacitor/file-transfer`	`@capawesome-team/capacitor-file-transfer`
`downloadFile({ url, path })`	`startDownload({ url, path })`, resolves with `{ id }`
`uploadFile({ url, path })`	`startUpload({ url, path })`, resolves with `{ id }`
`addListener('progress', ...)`	`addListener('transferProgress', ...)`
No equivalent	`transferCompleted` and `transferFailed` events
No equivalent	`pauseTransferById`, `resumeTransferById`, `cancelTransferById`
No equivalent	`getTransferById`, `getTransfers`

Availability

The plugin is part of the Capawesome Insiders subscription and requires Capacitor 8 or later. The full announcement is on our blog: Announcing the Capacitor File Transfer Plugin, and the plugin documentation covers the complete API.

Questions or feedback? Drop a comment — happy to answer.

Announcing the Capacitor Health Plugin

Robin — Wed, 26 Aug 2026 19:30:07 +0000

Health data on mobile lives in two stores: Apple HealthKit on iOS and Health Connect on Android. If you build a fitness or health app with Capacitor, you normally end up writing two integrations that disagree on permissions, sleep modeling, and even what a "workout" is. We just released the Capacitor Health plugin to solve exactly that: one strictly typed API that reads, writes, and aggregates data from both stores.

Why a Health Plugin Now

The timing follows the platforms. The Google Fit APIs shut down at the end of 2026, and Health Connect takes over as the health store on Android, while HealthKit has held that role on iOS all along. Any cross-platform health integration you build today should target these two stores — and ideally without maintaining two data models in your app code.

Aggregation First

Most health plugins hand you raw record lists and leave the math to you. That breaks the moment a user wears a smartwatch: the watch and the phone both record steps for the same minutes, and summing the records in JavaScript counts that overlap twice.

Both HealthKit and Health Connect solve this with native aggregation queries that deduplicate sources before returning a number, so the plugin is built around them. A week of daily step totals is one call:

import { DataType, Health } from '@capawesome-team/capacitor-health';

const readDailySteps = 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.map((bucket) => bucket.values[0].value);
};

The day, week, and month buckets are calendar-aware and follow the device's time zone. Cumulative data types such as steps, distance, and calories support sum; sampled types such as heart rate and weight support average, maximum, and minimum. An unsupported combination rejects with the INVALID_AGGREGATION error code instead of resolving with silently empty results, so a mistyped query fails in development instead of shipping as a dashboard full of zeros.

Availability and Permissions

Health Connect exists in three states on Android: available, not installed, or unsupported by the device. On Android 9 to 13 it's a separate app the user may not have; on Android 14 and later it's part of the operating system:

import { Health } from '@capawesome-team/capacitor-health';

const checkAvailability = async () => {
  const { available, reason } = await Health.isAvailable();
  if (!available && reason === 'health-connect-not-installed') {
    await Health.installHealthConnect();
  }
  return available;
};

Permissions are requested per data type and separately for reading and writing:

import { DataType, Health } from '@capawesome-team/capacitor-health';

const requestPermissions = async () => {
  const { permissions } = await Health.requestPermissions({
    read: [DataType.Steps, DataType.HeartRate, DataType.Sleep],
    write: [DataType.Weight],
  });
  return permissions;
};

An Honest Permission Model

Here's a HealthKit detail that surprises most developers: iOS deliberately hides whether a read permission was granted. A denied permission that is distinguishable from missing data would leak sensitive information — an app that knows it was denied blood glucose access could conclude the user is likely diabetic.

The plugin reports iOS read permissions as prompt before the first request and unknown afterwards, never as granted. Reporting granted would be an invented value, so the plugin doesn't do it. Design your app around the presence of data: request the permissions, query, and show a helpful empty state when nothing comes back.

Reading and Writing Records

When you need individual samples instead of aggregates, readRecords() returns them with timestamps and source, and writeRecord() logs the record types apps commonly write:

import { DataType, Health } from '@capawesome-team/capacitor-health';

const readHeartRateSamples = async () => {
  const { records } = await Health.readRecords({
    dataType: DataType.HeartRate,
    startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
  });
  return records;
};

const logWeight = async () => {
  await Health.writeRecord({
    dataType: DataType.Weight,
    startDate: new Date().toISOString(),
    value: 71.5,
  });
};

Workouts have their own reader: readWorkouts() returns exercise sessions with type, duration, and totals, whether logged by your app or another one.

Passing App Review

Health integrations fail review more often than they fail at runtime. Every Android app integrating with Health Connect must complete the Health apps declaration in the Google Play Console and provide a privacy policy; Apple reviews health apps against App Review Guideline 5.1.3. The plugin documentation includes dedicated sections for both, so the policy work is part of the setup instead of a surprise at submission time.

Availability

The Capacitor Health plugin covers around 20 data types, requires Capacitor 8 or later, and is available today as part of the Capawesome Insiders subscription. The full announcement with more details is on our blog: Announcing the Capacitor Health Plugin.

Questions or feedback? Drop a comment — happy to answer.

Google Play Contacts Policy 2027 for Capacitor

Robin — Thu, 13 Aug 2026 16:45:02 +0000

Google Play's new Contacts Permissions policy takes effect on January 27, 2027. Apps that target Android 17 (API level 37) or later may only declare READ_CONTACTS if the Android Contact Picker cannot cover their core functionality. If your Capacitor app only lets users pick a contact, you need to drop the permission, and with the Capacitor Contacts plugin that means passing the property option to pickContacts(...).

There is a catch that Google's announcement doesn't mention. Switching to the system contact picker does not by itself free you from READ_CONTACTS. Below Android 17, the picker hands your app an access grant so narrow that it contains no phone number, no email address, and no structured name (only a display name). This guide covers what the policy requires, why the picker alone falls short, and how to select a contact detail without ever asking for the permission.

Key Takeaways

Google Play's Contacts Permissions policy was announced on April 15, 2026 and becomes effective on January 27, 2027.
It applies to apps that target Android 17 (API level 37) or later. Those apps may only request READ_CONTACTS if the Android Contact Picker is not sufficient for their core functionality.
Apps that still need broad access must submit a Play Console declaration naming the features that require it and explaining why the picker falls short.
The contact picker grants read access to the picked contact URI only. That URI exposes no phone numbers, email addresses, or structured name, so reading contact details still requires READ_CONTACTS below Android 17.
The property option of pickContacts(...) lets the user select a single phone number, email address, or postal address. It requires no permission on any Android version and is available since version 8.1.0 of the Capacitor Contacts plugin.
On iOS, pickContacts(...) has never required a permission.

What Does Google Play's Contacts Permissions Policy Require?

The policy reserves READ_CONTACTS for apps that genuinely cannot work without the full address book. Google's wording is that apps which don't need broad access "must use the Android Contact Picker, a more secure, easy-to-integrate alternative that minimizes data collection and improves user safety."

Three details decide whether this affects you:

Who it applies to. Only apps that target Android 17 (API level 37) or later. Since Google Play raises the required target API level every year, that will be every actively maintained app soon enough.
When it lands. Google announced the policy on April 15, 2026 and set the effective date to January 27, 2027. Pre-review checks in the Play Console start on October 27, 2026, so you will see warnings before enforcement begins.
What the escape hatch costs. Apps that need ongoing access to the whole contact list keep it, but they have to file a Play Developer Declaration that names the user-facing feature and explains why the picker is technically insufficient. Automatic 30-day extensions are available through the Play Console.

A messaging app that syncs your address book to find friends has a case to make. A checkout screen that fills in a delivery address does not, and that second group is where most Capacitor apps sit.

Why Does the Contact Picker Still Need READ_CONTACTS?

Because the permission grant the picker returns is narrower than the data you asked for. When the user selects someone, the system grants your app read access to the picked contact URI, and that grant is exact: it covers that one URI and nothing below or beside it.

The problem is what lives at that URI. A row in the Contacts table holds an identifier and some metadata. It holds no phone numbers, no email addresses, and no structured name, because in Android's contacts model those live in the separate ContactsContract.Data table. Querying that table is a global read, and the grant does not extend to it. It does not extend to the contact's entities sub-directory either. Attempt it without the permission and the provider answers with a flat refusal:

Permission Denial: reading ContactsProvider2 uri content://com.android.contacts/contacts/1/entities requires android.permission.READ_CONTACTS

So "use the picker instead of the permission" is only half an instruction below Android 17. The picker gives you a contact you are allowed to identify but not allowed to read. There is no permission-free way to pull a whole contact record on those versions, which is why the plugin needs a different approach rather than a different intent.

How to Pick a Contact Without the READ_CONTACTS Permission

Ask the picker for a single contact property instead of a whole contact. The property option of pickContacts(...) launches the picker against the phone, email, or postal address table directly, so the user selects one specific value rather than a person:

import { ContactProperty, Contacts } from '@capawesome-team/capacitor-contacts';

const pickPhoneNumber = async () =&gt; {
  const { contacts } = await Contacts.pickContacts({
    property: ContactProperty.PhoneNumber,
  });

  return contacts[0]?.phoneNumbers?.[0]?.value;
};

This works because the picker now returns a data row URI, and the access it grants points at the row that actually holds the value. Your app reads it directly, on every Android version, without a permission in the manifest and without a runtime prompt. To install the Capacitor Contacts plugin, please refer to the Installation section in the plugin documentation.

ContactProperty offers three values, matching the three data tables the system picker can target:

Value	Selects	Read from
`ContactProperty.PhoneNumber`	A single phone number	`phoneNumbers`
`ContactProperty.EmailAddress`	A single email address	`emailAddresses`
`ContactProperty.PostalAddress`	A single postal address	`postalAddresses`

The result is deliberately thin. You get the contact id, the new displayName property, and the property the user picked, and nothing else:

const { contacts } = await Contacts.pickContacts({
  property: ContactProperty.EmailAddress,
});

const contact = contacts[0];

console.log(contact.displayName); // 'John Doe'
console.log(contact.emailAddresses?.[0].value); // 'john.doe@example.com'

displayName is a read-only property added in version 8.1.0. It holds the formatted name the device itself shows for the contact, derived from CNContactFormatter on iOS and Data.DISPLAY_NAME on Android, and it is the only name the granted URIs expose. Setting it when creating or updating a contact has no effect, so keep using givenName and familyName for that.

Practically, this changes how you design the interaction. Instead of one "Choose a contact" button followed by a disambiguation dialog when someone has four phone numbers, you send the user straight into a picker that lists the numbers. Fewer taps for them, no permission prompt for you.

What Changes on Android 17?

Android 17 makes plain contact picking permission-free on its own. Apps targeting API level 37 get their ACTION_PICK intent automatically upgraded to the new system contact picker, which returns a picker session URI following the ContactsContract.Data schema. The plugin detects that URI and reads it directly, so a call to pickContacts(...) without the property option also stops needing READ_CONTACTS there.

That does not make the property option redundant. Your app still runs on Android 16 and below, where the old behavior applies, and you cannot ship a manifest that declares READ_CONTACTS on old devices but not on new ones. As long as you support anything below Android 17, the property option is what lets you leave the permission out entirely.

When Do You Still Need READ_CONTACTS?

Whenever your app reads the address book without the user pointing at a specific entry. Every method that queries contacts on its own terms falls in this group:

getContacts(...) and getContactById(...), which read the address book directly.
countContacts(), getGroups(), and getAccounts().
Anything that syncs, backs up, or matches the full contact list against a server.

If your app does one of these as a core feature, the policy does not shut you out. Keep the permission and file the declaration. What the policy targets is the app that declares READ_CONTACTS to power a single "pick a friend" screen, and that app now has a cheaper option.

Two methods need no permission at all and are worth knowing about: displayCreateContact(...) hands the whole creation flow to the system UI, and on iOS pickContacts(...) has always run without one, because CNContactPickerViewController returns the selected contact to the app without touching the contacts entitlement.

How to Migrate Your Capacitor App

Work through it in this order:

Find every contacts call in your codebase. Search for Contacts. and sort the hits into two buckets: user-driven selection, and everything else.
Rewrite the selection calls. Replace pickContacts() with a property variant and adjust the code that consumes the result, since it now receives one value instead of a full contact object.
Decide about the rest. If the second bucket is empty, you are done and the permission can go. If it isn't, check whether those features are genuinely core to your app or leftovers you can drop.
Remove the permission. Delete `from yourAndroidManifest.xml. LeaveWRITE_CONTACTS` alone if you create or update contacts, as this policy does not cover it.
Test on a real device. Build with the permission removed and run every flow that touches contacts. A missing grant surfaces as a Permission Denial in Logcat, not as a friendly error, so watch the log while you click through.
File the declaration if you kept the permission. Do it before pre-review checks start on October 27, 2026 rather than in the week before the January deadline.

FAQ

When does Google Play's Contacts Permissions policy take effect?

January 27, 2027. Google announced it on April 15, 2026, and pre-review checks in the Play Console begin on October 27, 2026, which gives you roughly three months of warnings before enforcement. Automatic 30-day extensions can be requested through the Play Console.

Does the policy apply if my app targets Android 16?

Not yet. The policy covers apps that target Android 17 (API level 37) or later. Google Play raises the minimum target API level for updates every year, though, so an app that is still maintained will reach API 37 on its own schedule. Migrating early costs less than migrating under a deadline.

Does this affect my app on iOS?

No. This is a Google Play policy and applies to Android only. On iOS, pickContacts(...) never required the contacts permission, and the property option behaves the same way there, returning the id, the displayName, and the selected property.

Can I still read a full contact after the user picks one?

Only with READ_CONTACTS below Android 17. The picker's grant covers the picked contact URI, which carries no phone numbers, email addresses, or structured name, and reading those means querying the ContactsContract.Data table, which the grant does not cover. From Android 17 on, the upgraded system picker returns a data-schema URI that the plugin reads without the permission.

What happens if I keep READ_CONTACTS without filing a declaration?

Once the policy is effective, apps targeting Android 17 or later that declare the permission without an approved declaration are subject to enforcement, which in practice means your app updates get blocked in the Play Console. The declaration itself asks which user-facing features need the permission and why the Android Contact Picker is technically insufficient.

Does the property option work on older Android versions?

Yes. Picking against the phone, email, or postal address table is not an Android 17 feature. The picker returns a data row URI it grants access to on every supported Android version, which is exactly what makes the option a safe way to remove the permission from your manifest today.

Conclusion

The migration is smaller than the policy makes it sound. For most Capacitor apps it comes down to one option on one method call and one line deleted from the Android manifest. What takes the thinking is the audit: knowing which of your contacts calls are user-driven selection and which ones read the address book on their own, because only the second group needs a declaration.

For a full tour of the plugin's API, from permissions to accounts and groups, read Exploring the Capacitor Contacts API. If you have questions, join the Capawesome Discord server, and subscribe to the Capawesome newsletter to stay up to date with new plugins and guides.