DEV Community: Robin

Google Play DEX Code Optimization in Capacitor Apps

Robin — Sat, 10 Oct 2026 15:30:20 +0000

If Play Console shows a "DEX code optimization" finding for your Capacitor app, the Android project template is the cause. From February 2027, Google Play requires at least 25% obfuscation, optimization and shrinking for every app with more than 10 MB of DEX code, and the Capacitor Android template ships with R8 turned off. In this post, we walk through the fix: two lines in build.gradle, a short proguard-rules.pro, and one check before you upload.

Prerequisites

You'll need:

A Capacitor 8 Android app
Android Gradle Plugin (AGP) 8.x

Everything below comes from our own production app at Capawesome, which uses about 40 plugins and runs on Capacitor 8.5.0 with AGP 8.13.2.

Play's DEX optimization requirement

Google Play measures three percentages for every app bundle you upload: obfuscation, optimization and shrinking. A Capacitor app built from the default template scores close to zero on all three. The Android project that npx cap add android generates sets minifyEnabled false in the release build type, so R8 never touches your DEX code. For our app, Play Console reported 1% obfuscation.

The Play Console technical quality requirements say that from February 2027, apps need at least 25% in each category, and that "not meeting a requirement can affect an app's visibility and publishing capabilities on Google Play". The thresholds apply to apps with more than 10 MB of DEX code and to games with more than 50 MB. Capacitor, Firebase and Play Services dependencies put a plugin-heavy app over the 10 MB line.

The Android vitals page on DEX code optimization explains that for apps built with AGP 8.10 or higher, Play reads them from the r8.json file inside the bundle. Any shrinker counts, and R8 is the one every Android project already has.

Enable R8

Open android/app/build.gradle, set minifyEnabled true in the release build type and switch the default rules file to the optimizing variant:

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

The template points to proguard-android.txt. That file contains -dontoptimize, which blocks most of what R8 could do, and AGP 9 no longer accepts it by default. We covered that build failure in How to Fix Capacitor Plugin Build Errors with AGP 9, so switching now avoids it later.

R8 has run in full mode by default since AGP 8.0. That detail is behind the keep rule in the next section.

Rules you need

On top of the rules that Capacitor, AGP and the large SDKs contribute on their own, a Capacitor app needs these lines in android/app/proguard-rules.pro:

# Capacitor annotations: required in R8 full mode (ionic-team/capacitor#8589)
-keep @interface com.getcapacitor.** { *; }

# Plugin-specific rules from each plugin's README
-keep class io.capawesome.capacitorjs.plugins.** { *; }

# Optional backends that plugins probe for at runtime (see missing_rules.txt)
-dontwarn io.requery.android.database.**
-dontwarn net.zetetic.database.**

The first rule is the one every Capacitor app needs, and we'll explain it below. The second line is an example of a plugin-specific rule. Most Capacitor plugins ship no consumer rules, and a plugin that relies on reflection or serialization documents its rule in its README. The Capacitor SQLite plugin does exactly that for the io.capawesome.capacitorjs.plugins package. The -dontwarn lines depend on which plugins you use; the "Missing class errors" section shows how to find yours.

The rest is already handled for you:

Capacitor's consumer rules: @capacitor/android declares its own proguard-rules.pro as consumer rules. They keep every class annotated with @CapacitorPlugin, its public @PluginMethod methods, and its @PermissionCallback and @ActivityCallback methods, even private ones. Capacitor resolves those callbacks by method name at runtime, so permission requests and activity results survive R8 without any rule of yours.
AGP's defaults: they keep @JavascriptInterface methods, which is how Capacitor's MessageHandler receives calls from JavaScript.
Large SDKs: Firebase and Play Billing ship consumer rules of their own.

Why the keep rule

Without the @interface rule, the build passes and the app crashes on startup. Capacitor's consumer rules keep the classes annotated with @CapacitorPlugin, but not the annotation types themselves. Here is what the first launch of our minified build looked like in logcat:

FATAL EXCEPTION: CapacitorPlugins
java.lang.RuntimeException: java.lang.reflect.InvocationTargetException
Caused by: java.lang.NullPointerException
    at com.getcapacitor.Plugin.getPermissionStates
    at com.getcapacitor.Plugin.checkPermissions
    at ...FirebaseMessagingPlugin.checkPermissions

According to the Android documentation on R8 full mode, R8 strips annotations from classes that are not explicitly kept. Once the CapacitorPlugin annotation is gone, getAnnotation(CapacitorPlugin.class) can only return null. R8 then removes the pluginAnnotation field from PluginHandle, and Bridge.getPermissionStates() dereferences null the first time any plugin checks its permissions. All plugins still register, because registration only needs the class.

The -keep @interface com.getcapacitor.** { *; } rule keeps every annotation type in the package. That covers @CapacitorPlugin, @Permission, @PermissionCallback, @ActivityCallback, @PluginMethod and the legacy @NativePlugin.

Capacitor does not ship this rule in its consumer rules yet. Issue #8589 describes the same behavior with the same workaround and is open as of this writing. Capacitor 8.5.2 merged a null check in getPermissionStates(), so on 8.5.2 the app no longer crashes. Instead, checkPermissions() returns an empty permission map. You still need the keep rule on 8.5.2, because the null check only hides the symptom.

You could also avoid the crash by disabling full mode with android.enableR8.fullMode=false in gradle.properties. That costs you optimization across the whole app and all its dependencies, which is the exact number Play measures. The keep rule is the cheaper fix.

Missing class errors

R8 fails the build with "Missing class" errors when a plugin was compiled against a library your app does not bundle. Some Capacitor plugins do this on purpose. The Capacitor SQLite plugin compiles against both SQLCipher (net.zetetic.database.**) and requery's sqlite-android (io.requery.android.database.**) as compileOnly dependencies, and bundles only the one you select in variables.gradle. At runtime it probes for them with Class.forName. The missing classes are expected, but R8 can't know that, so the two -dontwarn lines above tell it.

Whenever R8 reports missing classes, it writes a ready-to-paste file to android/app/build/outputs/mapping/release/missing_rules.txt. Read each entry before you paste it:

A -dontwarn for an optional backend that the plugin checks for at runtime is correct.
A -dontwarn for a class a plugin calls unconditionally hides a real NoClassDefFoundError until a user hits it. The right fix there is to add the dependency.

Verify locally

Debug builds never run R8 with this configuration, so the release build is the only one that tells you whether your rules are complete. It also has to be signed before you can install it. The signing properties that Android Studio injects into Gradle let you sign a local release build with the debug keystore, without touching build.gradle:

cd android
./gradlew assembleRelease \
  -Pandroid.injected.signing.store.file=$HOME/.android/debug.keystore \
  -Pandroid.injected.signing.store.password=android \
  -Pandroid.injected.signing.key.alias=androiddebugkey \
  -Pandroid.injected.signing.key.password=android
adb install -r app/build/outputs/apk/release/app-release.apk

With the build installed, run three checks:

Watch logcat for FATAL EXCEPTION, ClassNotFoundException and NoSuchMethodException while the app starts. Then run every flow that requests a permission or waits for another activity, such as the camera, a file picker or a settings screen. The annotation crash shows up within the first second.
Open mapping.txt in android/app/build/outputs/mapping/release/ and confirm that your plugin classes still appear under their original names. A renamed plugin class means a keep rule is missing. Archive this file with every release, because you'll need it for production stack traces.
Read the Play numbers from the bundle before you upload it. Build it with ./gradlew bundleRelease and run unzip -p app/build/outputs/bundle/release/app-release.aab BUNDLE-METADATA/com.android.tools/r8.json. Play Console shows the same percentages for that upload in the app bundle explorer.

Conclusion

Our advice: enable R8 now, not when the February 2027 deadline arrives. The first minified build of a plugin-heavy Capacitor app surfaces every missing rule at once, and you want that to happen on an emulator, not in a Play release. Treat the release build as a standing test target. Run your permission and activity-result flows on it before every upload, and check missing_rules.txt again whenever you add a plugin. For the other Android build pitfalls Capacitor apps run into, see The Android Troubleshooting Guide for Capacitor.

The full post on the Capawesome blog also has an FAQ on mapping files for Play and Crashlytics and on resource shrinking, and if you have questions, drop them in the comments below.

How to Add Geofencing to an Ionic App

Robin — Fri, 09 Oct 2026 15:30:05 +0000

In this tutorial, we build a store reminder page in Ionic Angular: switch on a toggle for a store, and when you later walk within 200 meters of it, your phone reminds you to open your shopping list, even if the app was closed hours ago. You will learn how to request background location in two steps, register and remove geofences, show a native notification per geofence and read the transitions your app missed.

Most Ionic geofencing tutorials still use cordova-plugin-geofence, whose last release (0.7.0) dates from 2017. We use a Capacitor plugin built on the native region monitoring of Android and iOS instead.

Prerequisites

An Ionic Angular app on Capacitor 8 with standalone components.
The Capacitor Geofences plugin. Full transparency: we build this plugin at Capawesome. It is part of Capawesome Insiders, a paid subscription. For setup, see the Installation section of the docs.
The ACCESS_BACKGROUND_LOCATION permission on Android and the two location usage strings on iOS (see below).

All plugin logic lives in one GeofenceService with signals. The plugin calls are plain TypeScript, so they work in Ionic React or Vue too.

Platform setup

The plugin needs no capacitor.config.ts keys. On Android, it already declares ACCESS_FINE_LOCATION, POST_NOTIFICATIONS and RECEIVE_BOOT_COMPLETED, and you add background location yourself in android/app/src/main/AndroidManifest.xml:

That line is left to you because Google Play reviews it: the background location policy requires it to serve core functionality, a Permissions Declaration Form in the Play Console, and a prominent in-app disclosure before the request. For our page, that's a short screen before the first toggle triggers the permission flow.

On iOS, add both usage descriptions to ios/App/App/Info.plist:

NSLocationWhenInUseUsageDescription
The app needs access to your location to remind you when you are near a store.
NSLocationAlwaysAndWhenInUseUsageDescription
The app needs access to your location to remind you when you are near a store, even while it is closed.

Per Apple's authorization guide, "authorization requests fail immediately if the required keys aren't present", and the plugin rejects with an explicit error in that case.

Request permissions

Geofencing needs background location (Always on iOS). Both platforms expect it as a second step, so we call requestPermissions(...) first with location and then with backgroundLocation:

async requestPermissions(): Promise {
  let status = await Geofences.requestPermissions({
    permissions: ['location'],
  });
  if (status.location !== 'granted') {
    return false;
  }
  status = await Geofences.requestPermissions({
    permissions: ['backgroundLocation'],
  });
  if (status.backgroundLocation !== 'granted') {
    return false;
  }
  await Geofences.requestPermissions({ permissions: ['notifications'] });
  return true;
}

From Android 11, the background permission dialog no longer offers the option, so the plugin opens the location settings where the user picks "Allow all the time". On iOS, it shows the prompt that upgrades to Always, and Apple notes you "can make the request only once". The third call covers notifications, required on Android 13+.

Ask in context, when the user switches on the first toggle. With only foreground location, addGeofences(...) rejects with PERMISSION_DENIED. Once checkPermissions() reports denied, a button calling openSettings() is the way back.

Register a geofence

addGeofences(...) hands circular regions to the operating system, each with an id, a center and a radius in meters. Here is the service with a Store model, add(...) and a notification helper:

import { Injectable, signal } from '@angular/core';
import { Geofences, GeofenceTransition } from '@capawesome-team/capacitor-geofences';

export interface Store {
  id: string;
  name: string;
  latitude: number;
  longitude: number;
}

@Injectable({ providedIn: 'root' })
export class GeofenceService {
  readonly activeIds = signal([]);
  readonly lastTransition = signal(null);

  async add(store: Store): Promise {
    if (!(await this.requestPermissions())) {
      return;
    }
    await Geofences.addGeofences({
      geofences: [
        {
          id: store.id,
          latitude: store.latitude,
          longitude: store.longitude,
          radius: 200,
          notifyOnEnter: true,
          notifyOnExit: false,
          notification: this.reminderFor(store),
        },
      ],
    });
    this.activeIds.update((ids) =&gt; (ids.includes(store.id) ? ids : [...ids, store.id]));
  }

  private reminderFor(store: Store) {
    return {
      title: `You are near ${store.name}`,
      text: 'Open your shopping list before you go in.',
    };
  }

  // requestPermissions() from the previous section
}

Using the store's own id links the geofence to your data. Enter and exit both default to true; we only want arrivals. Android adds dwell via androidNotifyOnDwell and androidLoiteringDelay, iOS has none. Geofences never expire, so you remove them yourself.

Why 200 meters? Apple's region monitoring sample uses it, and Apple's archived guide assumes "approximately 200 meters" as the minimum distance for testing purposes. Android's geofencing guide suggests at least 100 to 150 meters. At the top end, iOS reports a monitoring failure for regions above maximumRegionMonitoringDistance, so the plugin clamps the radius to that maximum.

The OS caps the count at 20 regions per app on iOS and 100 on Android. Beyond that, addGeofences(...) rejects with GEOFENCE_LIMIT_EXCEEDED, so register the nearest stores and swap them as the user moves. Also, Android fires an enter transition right away if the device is already inside, while iOS waits for a boundary crossing. Why Are Your Geofences Not Triggering on iOS? explains why.

Handle transitions

The geofenceTransition event delivers each transition under event.transition, with a geofenceId, a type ('ENTER', 'EXIT' or 'DWELL') and a timestamp. latitude and longitude are always null on iOS, so look stores up by geofenceId.

The event only fires while the app is running with the listener attached, and background transitions are not replayed. Use it to update the open page, not for anything the user must not miss. The listener is registered in start() below.

Notify the user

The per-geofence notification (our reminderFor(...)) is how you reach a user whose app is closed. The operating system shows it on a transition even when the app is in the background or not running. The text is fixed at registration and shows on exits too, which is another reason notifyOnExit is false.

Skip @capacitor/local-notifications here: a notification scheduled from the listener can't cover the closed app and might duplicate the plugin's.

Queue missed transitions

The transition queue is off until you call setConfig(...) with maxSize. Then the plugin records every transition on the device whether or not your app runs. The queue survives restarts and reboots, holds 1,000 entries by default and drops the oldest when full.

The rest of the service enables the queue, listens, drains with getQueuedTransitions(...) and deleteQueuedTransitions(...), and restores and removes geofences:

async start(): Promise {
  await Geofences.setConfig({ maxSize: 1000 });
  await Geofences.addListener('geofenceTransition', (event) =&gt; {
    this.lastTransition.set(event.transition);
  });
  await this.drainQueue();
  document.addEventListener('visibilitychange', () =&gt; {
    if (document.visibilityState === 'visible') {
      this.drainQueue();
    }
  });
}

async drainQueue(): Promise {
  let hasMore = true;
  while (hasMore) {
    const result = await Geofences.getQueuedTransitions({ limit: 100 });
    if (!result.transitions.length) {
      break;
    }
    await this.persist(result.transitions);
    await Geofences.deleteQueuedTransitions({
      upToId: result.transitions[result.transitions.length - 1].id,
    });
    hasMore = result.hasMore;
  }
}

async restore(): Promise {
  const { geofences } = await Geofences.getGeofences();
  this.activeIds.set(geofences.flatMap((geofence) =&gt; geofence.id ?? []));
}

async remove(id: string): Promise {
  await Geofences.removeGeofences({ ids: [id] });
  this.activeIds.update((ids) =&gt; ids.filter((activeId) =&gt; activeId !== id));
}

persist(...) is your own storage or API call. Since reading and deleting are separate, a crash in between keeps the transitions queued, and upToId deletes everything up to that id. Live transitions are queued too, so the queue is your source of truth.

setConfig(...) replaces the whole config, so if you add a native upload url later, pass it with maxSize (details in the announcement post).

Remove geofences

Geofences persist across launches, so restore() reads the toggle state from getGeofences(). On Android, the plugin re-registers them after a reboot or app update; on iOS, the OS persists the regions. A toggle off calls removeGeofences(...), and removeAllGeofences() clears everything on sign-out.

The standalone page renders one toggle per store and the last live transition:

import { Component, OnInit, inject } from '@angular/core';
import {
  IonContent,
  IonHeader,
  IonItem,
  IonList,
  IonNote,
  IonTitle,
  IonToggle,
  IonToolbar,
} from '@ionic/angular/standalone';
import { GeofenceService, Store } from './geofence.service';

@Component({
  selector: 'app-stores',
  imports: [IonContent, IonHeader, IonItem, IonList, IonNote, IonTitle, IonToggle, IonToolbar],
  template: `


        Store reminders




        @for (store of stores; track store.id) {


              {{ store.name }}


        }

      @if (geofenceService.lastTransition(); as transition) {
        {{ transition.type }} at {{ transition.geofenceId }}
      }

  `,
})
export class StoresPage implements OnInit {
  readonly geofenceService = inject(GeofenceService);
  readonly stores: Store[] = [
    { id: 'store-berlin', name: 'Berlin Mitte', latitude: 52.52, longitude: 13.405 },
    { id: 'store-cupertino', name: 'Cupertino', latitude: 37.33182, longitude: -122.03118 },
  ];

  async ngOnInit(): Promise {
    await this.geofenceService.start();
    await this.geofenceService.restore();
  }

  async toggle(store: Store, checked: boolean): Promise {
    if (checked) {
      await this.geofenceService.add(store);
    } else {
      await this.geofenceService.remove(store.id);
    }
  }
}

In a real app, stores comes from your API, and start() runs once at app startup.

Conclusion

Test with real movement before shipping: install a build on a phone, register a store a few hundred meters away, close the app and walk across the boundary. Simulators confirm permissions and that getGeofences() returns your regions, but delivery timing only shows on a device. If the reminder works on Android but not on iPhone, the iOS troubleshooting post above lists the causes.

The full post on the Capawesome blog includes an FAQ on closed apps, region limits and React or Vue, and if you have questions, ask in the comments.

Reading Step Counts on iOS and Android with Capacitor

Robin — Thu, 08 Oct 2026 15:30:11 +0000

Showing a user's daily step count sounds like a one-liner: read the step records for today and add them up. In practice that number comes out higher than the one in the Health app, because the phone, a watch and fitness apps all record the same walk. In this guide, you'll see how to read step counts in a Capacitor app from Apple HealthKit and Health Connect, get today's total and a 7-day chart, and avoid counting steps twice.

Prerequisites

A Capacitor 8 app.
The Capacitor Health plugin. Full disclosure: we build this plugin at Capawesome, and it's part of Capawesome Insiders, a paid subscription. For setup, see the Installation section.
Android: android.permission.health.READ_STEPS declared in your own AndroidManifest.xml, the privacy policy meta-data entry from the plugin docs, and minSdkVersion set to 26.
iOS: the HealthKit capability enabled and NSHealthShareUsageDescription in Info.plist.

Where steps come from

On iOS, steps live in Apple HealthKit; on Android, in Health Connect. Both hold individual samples, each with a time range, a value and the app or device that wrote it. Apple's stepCount documentation notes that "the system automatically records samples on iPhone and Apple Watch", and a running app can add its own samples for the same walk. So your morning commute may sit in the store two or three times.

Health Connect ships with Android 14 (API level 34) and later. On Android 9 to 13, it's a separate Play Store app, which matters for the next step.

Check availability

Not every device has a health store, so start with isAvailable(). It resolves with available and a reason, which is null when the store is ready and otherwise one of:

health-connect-not-installed: Health Connect is missing (Android 9 to 13).
health-connect-update-required: the installed Health Connect app is too old.
not-supported: no health store at all, for example Android below 9, iPadOS before 17 or visionOS.

For the first two, installHealthConnect() opens the Play Store page:

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

const ensureHealthStore = async () =&gt; {
  const { available, reason } = await Health.isAvailable();
  if (available) {
    return true;
  }
  if (reason === 'health-connect-not-installed' || reason === 'health-connect-update-required') {
    await Health.installHealthConnect();
  }
  return false;
};

After opening the store, check again when the user comes back, and hide the step feature completely for not-supported.

Request step permission

Once the native setup from the prerequisites is in place, request read access for DataType.Steps with requestPermissions(...). On iOS, Apple warns that "your app will crash when you request authorization" without the usage keys, so the plugin checks for them and rejects with an error instead.

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

const requestStepAccess = async () =&gt; {
  const { permissions } = await Health.requestPermissions({
    read: [DataType.Steps],
  });
  const steps = permissions.find((permission) =&gt; permission.dataType === DataType.Steps);
  return steps?.read;
};

The two platforms report the result differently.

On Android, requestPermissions(...) returns denied right after a rejection, while checkPermissions(...) only reports granted or prompt. After two denials, Health Connect ignores further requests, so show a button that calls openSettings() once you see denied.

On iOS, a read permission is never reported as granted. You get prompt before the first request and unknown afterwards, because HealthKit hides read decisions for privacy. Apple's authorizationStatus(for:) documentation says a denied read looks as if "there is no data of the requested type in the HealthKit store." So request access, run the query, and treat an empty result as "no data or no access".

Today's total

Today's step count is one aggregate(...) call from local midnight until now:

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

const getTodaySteps = async () =&gt; {
  const startOfToday = new Date();
  startOfToday.setHours(0, 0, 0, 0);
  const { buckets } = await Health.aggregate({
    dataType: DataType.Steps,
    startDate: startOfToday.toISOString(),
    endDate: new Date().toISOString(),
    bucket: 'day',
    operations: ['sum'],
  });
  return buckets[0]?.values[0]?.value ?? null;
};

setHours(0, 0, 0, 0) sets midnight in the device's time zone. toISOString() writes UTC, so in Berlin during summer time the start of October 8 becomes 2026-10-07T22:00:00.000Z, which is the same instant.

You get one bucket with one value per operation, as a plain number in count. The value is null when there's no data. Keep null apart from 0 in your UI, since on iOS null can also mean the user denied access.

Daily and weekly buckets

For a 7-day chart, keep the day bucket and start at local midnight six days ago. Buckets align to startDate, and day, week and month follow the device's time zone. If you start at "now minus seven days" (as the README sample does), a call at 14:37 gives buckets from 14:37 to 14:37 that mix two calendar days. Starting at midnight fixes that:

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

const getWeekChartData = async () =&gt; {
  const start = new Date();
  start.setHours(0, 0, 0, 0);
  start.setDate(start.getDate() - 6);
  const { buckets } = await Health.aggregate({
    dataType: DataType.Steps,
    startDate: start.toISOString(),
    endDate: new Date().toISOString(),
    bucket: 'day',
    operations: ['sum'],
  });
  return buckets.map((bucket) =&gt; ({
    label: new Date(bucket.startDate).toLocaleDateString(undefined, { weekday: 'short' }),
    steps: bucket.values[0]?.value ?? 0,
  }));
};

setDate() works in local time, so the start stays at midnight across a daylight saving change, which subtracting 6 * 24 hours would not. For longer views, switch to week or month and start at midnight on the first day of your week or month.

Steps support only sum. Asking for average, maximum or minimum rejects with INVALID_AGGREGATION, so compute a daily average from the day buckets yourself.

The double-counting trap

Summing the records from readRecords(...) is the tempting shortcut:

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

const sumStepRecords = async (startDate: string, endDate: string) =&gt; {
  const { records } = await Health.readRecords({
    dataType: DataType.Steps,
    startDate,
    endDate,
  });
  return records.reduce((total, record) =&gt; total + (record.value ?? 0), 0);
};

For someone with an iPhone and an Apple Watch, both devices write samples for the same minutes, and this function counts them twice.

aggregate(...) avoids that because the platform does the math. On iOS, HealthKit computes totals with statistics queries, and Apple's HKStatistics documentation describes the default:

> By default, these queries automatically merge the data from all of your data sources before performing the calculations.

On Android, the Health Connect aggregate data guide (last updated September 23, 2026) states that "the Aggregate API accounts for any duplicate data and keeps only the data from the app with the highest priority." Steps are an Activity type, which that rule covers, and only the user can change the priority order.

Raw records are still useful for showing where steps came from. Each record has sourceBundleId and sourceName (always null on Android):

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

const getStepsBySource = async (startDate: string, endDate: string) =&gt; {
  const { records } = await Health.readRecords({
    dataType: DataType.Steps,
    startDate,
    endDate,
  });
  const totals = new Map();
  for (const record of records) {
    const source = record.sourceName ?? record.sourceBundleId ?? 'Unknown';
    totals.set(source, (totals.get(source) ?? 0) + (record.value ?? 0));
  }
  return totals;
};

Show these as what each source recorded, never as parts of a total: they won't add up to the aggregate(...) result.

Platform limits

History on Android: Health Connect allows reads from up to 30 days before the first permission grant. Google's read data guide (last updated September 24, 2026) names READ_HEALTH_DATA_HISTORY for older data. Support is planned in the plugin; until then, keep Android ranges inside that window.
No background reads: the plugin has no background or observer API, so data refreshes when the user opens the app.
On-device steps on Android 14+: with SDK Extension 20 or higher, Health Connect counts steps on the device once any app holds READ_STEPS. aggregate(...) includes them, and since a June 2026 update they're credited to a device-specific package name instead of android.

Conclusion

Use aggregate(...) for every step number you display (today's total, a weekly chart, a monthly goal) and start each range at local midnight. Reach for readRecords(...) only when users want to see which device or app recorded their steps.

The full post on our blog, including an FAQ on Google Fit and older history, is at How to read step counts in a Capacitor app, and if you have questions, drop them in the comments.

How to Fix AdMob Banner Overlap in a Capacitor App

Robin — Wed, 07 Oct 2026 15:30:04 +0000

You add an AdMob banner to your Capacitor app, run it on a device, and the Ionic tab bar is gone, hidden under the ad. In this guide, we'll look at why the banner covers your content and fix it two ways: by letting the plugin shrink the web view, or by reserving the exact banner height in CSS. We'll also cover the Ionic CSS for tab bars, content and floating action buttons, and what changes if you come from @capacitor-community/admob.

Prerequisites

A Capacitor 8 app, ideally with Ionic Framework.
Consent gathered and the Google Mobile Ads SDK initialized. The AdMob GDPR consent guide walks through that part.
The Capacitor AdMob plugin. For setup, see the Installation section of the docs.

Full transparency: we build this plugin at Capawesome, and it is part of Capawesome Insiders, a paid subscription. If you need a free option, @capacitor-community/admob is a maintained, MIT-licensed alternative, and the last section compares the two.

Why the banner overlaps

The Google Mobile Ads SDK renders the banner as a native view on top of the Capacitor web view. Your HTML is laid out as if the banner did not exist, so the ion-tab-bar slides under a bottom banner, a floating action button ends up behind it, or the last list row never scrolls into view.

This is an old problem. Issue #2 "Ad overlapping tabs" on the community plugin dates back to July 2020, and edge-to-edge layouts made it worse, as #390 from November 2025 shows for Android 15 and 16.

Hardcoding padding-bottom: 50px doesn't work either, because the default adaptive banner has no fixed height. Google's iOS banner guide caps anchored adaptive banners at 20% of the screen height with a 150px maximum, and the Android guide describes a 50 to 150 dp range. The plugin defaults to BannerSize.AdaptiveBanner and leaves the height to the SDK, so the only reliable number is the one the SDK reports after it picks a size.

Resize the web view

The fix with zero CSS is mode: 'resize'. Pass it to showBanner(...) and the plugin shrinks the web view so the banner never overlaps your web content. Your page still lays itself out at full height; the page is a bit shorter.

It works for top banners as well as bottom ones. Here the banner sits above an Ionic header, and we keep the returned id for later calls:

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

let topBannerId: string | undefined;

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

That ad unit is Google's Android test banner. On iOS, use ca-app-pub-3940256099942544/2934735716 during development.

Resize mode covers most apps with one anchored banner. Reach for something else when:

the banner belongs inside scrolling content (use a frame; ShowBannerOptions ignores position once a frame is set),
your layout should continue behind the banner, like a full-screen map or game canvas,
a changing viewport height makes your CSS or resize listeners jump visibly.

Pad in overlay mode

Overlay is the default mode. The web view stays full size, and the banner sits on top of it, anchored to the top or bottom edge and safe-area aware, so it stays clear of the home indicator and gesture bar. Keeping content out from under it is your CSS's job.

The bannerSizeChanged event tells you how much space to reserve. Its payload carries the banner id plus width and height in CSS pixels, so the value goes straight into a CSS custom property with no unit conversion. Register the listener once and before you call showBanner(...), otherwise the first size event can arrive before anything is listening. We keep the handle so a second call to showBottomBanner() doesn't add a second handler:

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

const BANNER_ID = 'bottom-banner';
let bannerHeight = 0;
let sizeListener: PluginListenerHandle | undefined;

const setBannerInset = (height: number) => {
  document.documentElement.style.setProperty('--admob-banner-height', `${height}px`);
};

const addBannerSizeListener = async () => {
  if (sizeListener) {
    return;
  }
  sizeListener = await Admob.addListener('bannerSizeChanged', ({ id, height }) => {
    if (id !== BANNER_ID) {
      return;
    }
    bannerHeight = height;
    setBannerInset(height);
  });
};

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

Why pass our own id? The listener exists before showBanner(...) resolves, so it can't compare against a returned identifier yet, but it can compare against a constant. The check also stops a second banner, say an inline one, from overwriting the bottom inset with its own height.

The property lives on document.documentElement (the :root element), so any component can read it with var(--admob-banner-height, 0px). The 0px fallback keeps the layout correct on the web and before the first event.

Ionic layout specifics

Which element gets the banner height depends on what sits at the bottom of your page. With tabs, move the ion-tab-bar up:

ion-tab-bar {
  margin-bottom: var(--admob-banner-height, 0px);
}

Don't add env(safe-area-inset-bottom) or --ion-safe-area-bottom to that margin. Ionic's tab bar and footer already pad themselves for the bottom inset, and the overlay banner already sits above it, so adding it again makes the tab bar grow by the height of the gesture bar. The same goes for ion-footer.

Pages without a tab bar or footer need the space inside ion-content. Its --padding-bottom extends the scrollable area so the last item can scroll above the banner. A bottom ion-fab is positioned against ion-content itself, not its scroll padding, so it needs its own margin:

ion-content {
  --padding-bottom: var(--admob-banner-height, 0px);
}

ion-fab[vertical="bottom"] {
  margin-bottom: var(--admob-banner-height, 0px);
}

If some pages run without ads, scope these rules with a class on the page component. On a tabbed page you can skip the content and FAB rules entirely, because the raised tab bar already shortens the area above it.

Hide, resume, remove

Hiding a banner doesn't reset the space you reserved for it, so the CSS variable has to follow visibility. hideBanner(...) keeps the ad loaded but invisible, and resumeBanner(...) shows it again. Reusing BANNER_ID, bannerHeight and setBannerInset from above, one function handles both:

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

const setBannerVisible = async (visible: boolean) => {
  if (visible) {
    await Admob.resumeBanner({ id: BANNER_ID });
    setBannerInset(bannerHeight);
  } else {
    await Admob.hideBanner({ id: BANNER_ID });
    setBannerInset(0);
  }
};

We restore the last known height on resume instead of waiting for an event, since the README doesn't say that resuming fires bannerSizeChanged. When a user buys your ad-free tier, call removeBanner(...), set the inset to 0, and call remove() on sizeListener before clearing it.

Collapsible banners need no extra code. With collapsible: true, the banner expands and collapses, firing bannerSizeChanged each time, and the listener keeps the tab bar or padding in sync in both directions.

Community plugin comparison

@capacitor-community/admob gives the same core advice: the banner is drawn above the WebView, and you pad your content from its bannerAdSizeChanged event. It's free, while the Capacitor AdMob plugin requires Insiders and is still marked experimental in its README. Here's how they differ:

	`@capacitor-community/admob`	Capacitor AdMob plugin
Avoiding overlap	Pad content from the size event, or offset with `margin`	`mode: 'resize'`, or pad content from the size event
Offset option	`margin` in dp (Android) or points (iOS)	None
Position values	`TOP_CENTER`, `CENTER`, `BOTTOM_CENTER`	`'top'`, `'bottom'`, or a `frame`
Size event	`bannerAdSizeChanged` with `{ width, height }`	`bannerSizeChanged` with `{ id, width, height }`
Units	dp (Android) and points (iOS)	CSS pixels
Banners at once	One	Several, each with its own `id`
Android SDK	Legacy Google Mobile Ads SDK 25.4.x	Next-Gen Google Mobile Ads SDK
License	MIT	Capawesome Insiders (paid)

The unit gap is smaller than it looks. The Android WebView sets devicePixelRatio to the screen density factor, so one CSS pixel covers about one dp, and on iOS one CSS pixel equals one point at default zoom.

If you migrate, drop the margin workaround. Setting margin to the tab bar height is a fixed dp value that ignores edge-to-edge insets (see #390). Use mode: 'resize' or the ion-tab-bar rule instead.

The SDK row matters long term: Google's deprecation schedule deprecates the legacy Android SDK versions 24 and 25 on June 30, 2027, and sunsets them on June 30, 2028, after which ads are "at risk of not serving".

Conclusion

Start with mode: 'resize' for a single top or bottom banner. Switch to overlay plus bannerSizeChanged when content has to continue behind the banner or the viewport height must stay constant, and use a frame when the banner belongs inside your content. Before shipping, test on one device with gesture navigation and one with a notch, since the inset is where most remaining overlap comes from. The edge-to-edge and safe areas guide covers that CSS.

The full post has the FAQ (including whether the reported height includes the safe-area inset) and the inline placement details, and if you have questions, drop them in the comments.

Downloading Files in the Background in Capacitor

Robin — Tue, 06 Oct 2026 15:30:05 +0000

If your Capacitor app downloads a large file with fetch, the download dies as soon as the user switches apps for more than a few seconds. In this post, we look at why that happens, how to hand the download to the native transfer engines of Android and iOS, and what your app sees after the OS kills it or the user force-quits it.

Prerequisites

A Capacitor 8 app with Android and/or iOS platforms added.
The Capacitor File Transfer plugin. We build this plugin at Capawesome, and it is part of Capawesome Insiders, a paid subscription.

Why fetch stops

A download started with fetch, XMLHttpRequest or any other JavaScript API runs in the web view, inside your app's process. When iOS suspends that process, the download stops with it. Apple's background execution guide is clear about how fast that happens:

When your app moves to the background, the system calls your app delegate's applicationDidEnterBackground(_:) method. That method has five seconds to perform any tasks and return. Shortly after that method returns, the system puts your app into the suspended state.

You can request extra time with beginBackgroundTask(...), but that time is finite, and Apple warns that "if you don't end your tasks in a timely manner, the system terminates your app." A large video on a mobile connection rarely makes it.

Background-mode plugins that keep the web view alive go against Apple's rule that "a background app must do as little work as possible, and preferably nothing, because it's offscreen". Even when they work, an OS kill or a force-quit still ends the download together with the app.

The official plugins don't solve this either. The @capacitor/file-transfer docs (version 2.0.6 on npm) describe downloadFile(...) as downloading "the file to the specified destination" and say nothing about background or lifecycle behavior. The method returns a promise in JavaScript, so a relaunched app has no reference to a download the previous process started.

Native transfer engines

The Capacitor File Transfer plugin gives each platform the engine the OS designed for this job.

On iOS, it uses a background URLSession. Apple's guide to downloading files in the background explains why this works:

With background sessions, the actual transfer is performed by a process that is separate from your app's process.

iOS can suspend your app, or terminate it for memory, without touching the download, and then wakes or relaunches the app in the background to hand over the result. One limit: if your app starts a transfer while it's already in the background, the system treats the session as discretionary and decides when it runs. Start important downloads in the foreground.

On Android, the plugin runs transfers in a dataSync foreground service with its own OkHttp engine. Android's foreground service docs require a visible notification, "to make users aware that your app is performing a task in the foreground and is consuming system resources."

Android adds two more rules:

Apps targeting Android 12+ can't start a foreground service from the background. Since plugin version 0.1.2, a transfer that starts in that situation (for example, after waiting for Wi-Fi) runs without the service and its notification instead of failing.
Android 15 added a dataSync timeout: apps targeting API level 35+ get 6 hours per 24-hour period, shared across all their dataSync services. The timer resets when the user brings the app to the foreground.

Start a download

For installation, see the Installation section of the plugin docs. Once it's set up, startDownload(...) resolves immediately with an ID while the transfer continues in native code:

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

const downloadCoursePack = async (url: string, path: string) => {
  const { id } = await FileTransfer.startDownload({
    url,
    path,
    network: 'unmetered',
    maxRetries: 3,
    androidNotification: {
      title: 'Downloading course pack',
      text: 'The download continues in the background.',
      progress: true,
    },
  });
  return id;
};

Besides url and path, you can pass headers and method. The background behavior comes from three options:

network: 'unmetered' waits for Wi-Fi or a similar network. On Android, the transfer sits in the pending state meanwhile. Default is 'any'.
maxRetries: how often to retry after a network error, with backoff. Default is 0, which becomes important after an iOS force-quit.
androidNotification: title and text of the foreground service notification. progress: true adds a per-transfer progress bar, and channelName defaults to File Transfer.

Downloads are resumable by default if the server supports the HTTP Range header (see pause and resume).

Listen for results

Since the promise resolves before a single byte arrives, the plugin reports progress and results through events. Register the listeners once at app startup, not on the screen that started the download:

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

const addTransferListeners = async () => {
  await FileTransfer.addListener('transferProgress', event => {
    console.log(`Transfer ${event.id}: ${event.progress ?? 'unknown'}`);
  });
  await FileTransfer.addListener('transferCompleted', event => {
    console.log(`Transfer ${event.id} saved to ${event.path}`);
  });
  await FileTransfer.addListener('transferFailed', event => {
    console.error(`Transfer ${event.id} failed: ${event.errorCode}`, event.message);
  });
};

transferProgress fires about every 100 ms with bytes, totalBytes and a progress value between 0 and 1 (null if the server sends no size). transferCompleted carries the path and HTTP responseCode, and transferFailed carries errorCode, message and responseCode.

The plugin retains completed and failed events that fire while no listener is registered and delivers them once one is added. There's no such guarantee for progress events during suspension, so build your logic on the final events and treat progress as display only.

Platform setup

On iOS, you need one change. When a URL session finishes while your app isn't running, Apple's application(_:handleEventsForBackgroundURLSession:completionHandler:) docs explain that "the system launches your app in the background so that it can process the event." Forward that completion handler to the plugin from an AppDelegate extension:

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 it, transfers still complete, but iOS may not wake the app to deliver the final events promptly. No Info.plist entry or background mode is needed.

On Android, the plugin's own manifest declares the permissions and the dataSync service. The only runtime step is the notification permission on Android 13+, via requestPermissions():

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

const requestNotificationPermission = async () => {
  const { notifications } = await FileTransfer.requestPermissions();
  return notifications === 'granted';
};

If the user denies it, the notification is hidden but the transfer still runs.

What survives what

How far a download gets depends on how the app was closed:

App state	Android	iOS
Backgrounded	Keeps running in the `dataSync` foreground service.	Keeps running in the background `URLSession`.
Killed by the OS for memory	Interrupted, then restored as `failed`; downloads can be resumed.	Finished by the system and delivered when the app relaunches.
Force-quit by the user	Same as an OS kill.	Canceled by the system; retried on relaunch if `maxRetries` is above 0, otherwise restored as `failed` with a `transferFailed` event.

The iOS force-quit row comes straight from Apple's background(withIdentifier:) docs:

This behavior applies only for normal termination of the app by the system. If the user terminates the app from the multitasking screen, the system cancels all of the session's background transfers. In addition, the system does not automatically relaunch apps that were force quit by the user. The user must explicitly relaunch the app before transfers can begin again.

So the retry can only happen on relaunch, and only with maxRetries above 0. On Android, an interrupted download waits in failed until you call resumeTransferById(...), which continues from the bytes already on disk.

Restore after relaunch

getTransfers() returns every transfer the plugin knows about, including ones restored from the previous process. Call it on startup, after registering your listeners:

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

const restoreDownloads = async () => {
  const { transfers } = await FileTransfer.getTransfers();
  return transfers.filter(
    transfer => transfer.type === 'download' && transfer.state !== 'canceled',
  );
};

Each Transfer has its id, state, url, path, bytes and totalBytes, so you don't need your own persistence layer. A running download keeps reporting progress, a pending one waits for its network, and a failed one gets a resume button.

Listener order matters here. A download that iOS completed after an OS kill produces a transferCompleted event on relaunch, held until the first listener registers. If you only register listeners on the downloads screen, that event shows up there, possibly long after the file exists.

Conclusion

Use a native transfer for any download that takes more than a few seconds or that the user should be able to walk away from, and keep fetch for small requests that finish while the screen is open. Set maxRetries above 0 for user-started downloads so an iOS force-quit costs a relaunch instead of the download, and call getTransfers() on every launch so interrupted Android downloads get their resume button.

The full post has an FAQ and more details, and if you have questions, drop them in the comments.

Capacitor Barcode Scanning Without Google Play Services

Robin — Fri, 02 Oct 2026 15:42:31 +0000

Originally published on the Capawesome blog.

Barcode scanning works on Android devices without Google Play services, as long as the ML Kit model ships inside your app instead of being downloaded through Play services. That makes a Capacitor barcode scanner without Google Play services possible on Huawei phones released after May 2019, Amazon Fire tablets, and AOSP-based kiosk and rugged devices. This guide explains the bundled and unbundled ML Kit models, which methods of the free, open-source Capacitor ML Kit Barcode Scanning plugin rely on Play services, and how the Capacitor Barcode Scanner plugin avoids Play services on every path. The ML Kit plugin is an unofficial plugin maintained by Capawesome and is not affiliated with Google. The Barcode Scanner plugin is paid and part of the Capawesome Insiders subscription.

Key takeaways:

ML Kit barcode scanning comes as a bundled model linked into the app (about 2.4 MB) or an unbundled one downloaded via Google Play services (about 200 KB).
In the free Capacitor ML Kit Barcode Scanning plugin, startScan() and readBarcodesFromImage() use the bundled model, while scan() runs the Google code scanner and needs Google Play services.
The Capacitor Barcode Scanner plugin, part of the paid Capawesome Insiders subscription, uses the bundled model for every Android method and AVFoundation plus Vision on iOS.
The Capacitor Google Play Services plugin's getStatus() resolves to SERVICE_MISSING on devices without Play services, so an app can fall back from scan() to startScan() at runtime.
Only Android is affected, since iOS has no Google Play services and the ML Kit plugin's iOS model ships with the GoogleMLKit/BarcodeScanning pod.

Devices without Play services

Google describes Google Play services as "a core set of on-device background services that run on all Google-certified Android devices" in its Play services overview. Several groups of Android devices ship without it:

Huawei phones. Models released after May 2019 launched without Google Play services (Android Authority) and run Huawei's HMS Core instead. Huawei's own support article states that "certain Android apps require support from GMS Core and may not be able to run on HMS Core".
Amazon Fire tablets and Fire TV. Amazon's porting guide warns that an existing Android app "might use Google Play services, which isn't supported on Fire OS".
Enterprise, kiosk and rugged devices. Microsoft Intune offers an AOSP management solution for corporate-owned devices that are "Not integrated with Google Mobile Services". Some rugged and kiosk devices ship AOSP builds without GMS, and Zebra's GMS Restricted mode can switch Play services off on devices that have it.
Meta Quest. Meta's Horizon OS documentation states that "Horizon OS does not include Google Mobile Services, so calls into GMS APIs fail".
Mainland China. Google's Wear OS guide for China tells developers to "account for handsets without Google Play services pre-installed".
De-Googled systems. On LineageOS and GrapheneOS, Google Play is an optional, separate install.

A scanner that depends on Play services breaks on these devices. One example from outside Capacitor is expo/expo#39449, where expo-camera, a React Native library, crashed with an ActivityNotFoundException on Honor and Huawei devices because it tried to launch Google ML Kit's barcode scanning activity, which those devices don't have. For an enterprise app rolled out to a fleet of AOSP handhelds, these devices can be every install. If you distribute to Huawei users through their own store, Publish a Capacitor App on Huawei AppGallery covers the release side.

Bundled vs. unbundled model

Capacitor barcode scanning works without Google Play services when the Android side uses the bundled ML Kit model, because that model is statically linked into the app and nothing has to be downloaded through Play services. Google's Barcode Scanning guide for Android offers the model in two variants, and the last three rows below quote its comparison table:

Feature	Unbundled	Bundled
Gradle artifact	`com.google.android.gms:play-services-mlkit-barcode-scanning`	`com.google.mlkit:barcode-scanning`
Implementation	Model is dynamically downloaded via Google Play Services.	Model is statically linked to your app at build time.
App size	About 200 KB size increase.	About 2.4 MB size increase.
Initialization time	Might have to wait for model to download before first use.	Model is available immediately.

The unbundled model lives in Play services and is shared between apps. Google states that if the app doesn't request the download ahead of time, "the model is downloaded the first time you run the scanner. Requests you make before the download has completed produce no results." On a device without Play services, there is nothing to download it from. Google's advice on choosing between the two lists full functionality right after installation and offline use as reasons for bundled, and a smaller app plus automatic model updates through Play services as reasons for unbundled.

The Google code scanner is a third option, a complete scanning screen rather than a model. According to Google's code scanner guide, its "implementation resides entirely within Google Play services", and the installation paths page lists it as unbundled only. Google's document scanner is unbundled only as well, which is why the Capacitor Document Scanner plugin requires Play services on Android.

The com.google.mlkit.vision.DEPENDENCIES meta-data in AndroidManifest.xml only applies to modules that Play services delivers. It tells Play services to download them while the app is installed from the Play Store, so it has no effect on a bundled model and does nothing on devices without the Play Store.

To see which variant a plugin uses, read the artifact its android/build.gradle declares directly. com.google.mlkit:barcode-scanning is the bundled model, and com.google.android.gms:play-services-mlkit-barcode-scanning is the unbundled one. The resolved dependency tree won't tell you, because the bundled artifact's own POM depends on play-services-mlkit-barcode-scanning, so that client library shows up in bundled setups too. A com.google.android.gms library inside your APK is also not the same thing as the Google Play services app on the device.

The ML Kit plugin

The Capacitor ML Kit Barcode Scanning plugin declares two Google SDKs in its Android build.gradle, and each method uses one of them. The first, com.google.mlkit:barcode-scanning:17.3.0, is the bundled model, which the plugin has used since its first release in March 2023. The second, com.google.android.gms:play-services-code-scanner:16.1.0, is the Google code scanner.

startScan(...) and readBarcodesFromImage(...) run on the bundled model. scan(...) opens the Google code scanner, which the plugin's API reference describes as "only available on devices with Google Play Services installed". Our answers on GitHub confirm the split. Asked in issue #174 whether the plugin supports Huawei devices without Google Play services, we replied: "Yes, Huawei devices are supported but you have to use the startScan(...) method and build the UI yourself." In issue #219, a user's scanner module download failed in production with status FAILED = 5, and we named both artifacts: "com.google.mlkit:barcode-scanning is used by the startScan(...) method and is bundled. com.google.android.gms:play-services-code-scanner is used by the scan(...) method and cannot be bundled as far as I know."

A startScan() session needs the camera permission, a listener for the barcodesScanned event, and a CSS class that hides the web view elements covering the camera:

import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';

const startScan = async () => {
  const { camera } = await BarcodeScanner.requestPermissions();
  if (camera !== 'granted') {
    return;
  }
  document.body.classList.add('barcode-scanner-active');
  await BarcodeScanner.addListener('barcodesScanned', (event) => {
    console.log(event.barcodes);
  });
  await BarcodeScanner.startScan();
};

const stopScan = async () => {
  document.body.classList.remove('barcode-scanner-active');
  await BarcodeScanner.removeAllListeners();
  await BarcodeScanner.stopScan();
};

The barcode-scanner-active class is yours to define. startScan() renders the camera behind the web view, so the class has to make every element between the camera and the user transparent. Version 7 of the plugin replaced the older single-barcode event with barcodesScanned, which delivers an array in event.barcodes.

The trade-off is the UI and the permission. With startScan(), you build the scanning screen and declare the CAMERA permission yourself. With scan(), Google provides the screen and your app needs no camera permission on Android, but only on devices with Play services. The ML Kit plugin also parses structured payloads. Each Barcode carries a valueType and, depending on the content, fields such as wifi, contactInfo, driverLicense or calendarEvent, which the Insiders plugin does not offer yet.

Detect Play services first

With the Capacitor Google Play Services plugin, an app on the free ML Kit plugin can use scan() where Play services exists and fall back to startScan() everywhere else. The plugin is free, Android-only and depends only on the play-services-base library, whose availability check "works on any Android device, including devices without Google Play Services". getStatus() resolves to SERVICE_MISSING on devices where Play services is not installed at all, which the plugin documentation names for Huawei devices with Huawei Mobile Services, Amazon Fire devices and custom Android builds. The following function picks the scan method from that status:

import { BarcodeScanner } from '@capacitor-mlkit/barcode-scanning';
import { GooglePlayServices, Status } from '@capawesome/capacitor-google-play-services';

const scanBarcodeOnAndroid = async () => {
  const { status } = await GooglePlayServices.getStatus();
  if (status !== Status.Success) {
    await startScan();
    return;
  }
  const { barcodes } = await BarcodeScanner.scan();
  console.log(barcodes);
};

startScan is the function from the previous section. Run this branch on Android only, since the Google Play Services plugin has no iOS or web implementation. Because scan() requires Google Play services, make the check before the call rather than reacting to a failed scan. The function falls back for every status other than SUCCESS. SERVICE_MISSING is the Huawei and Fire OS case, while SERVICE_DISABLED, SERVICE_VERSION_UPDATE_REQUIRED and SERVICE_UPDATING mean Play services is installed but not usable yet, and makeAvailable() prompts the user to fix that before you offer scan().

A SUCCESS status does not guarantee that the scanner module is on the device yet. The ML Kit plugin's documentation recommends isGoogleBarcodeScannerModuleAvailable() as the plugin-level check before scan() on Android, and installGoogleBarcodeScannerModule() starts the download when the module is missing.

The Insiders plugin

The Capacitor Barcode Scanner plugin uses the bundled ML Kit model for every Android method, including its ready-made scanner UI. Its documentation lists this as a feature: "Uses the bundled ML Kit model, so scanning works offline and without Google Play services." The Android notes add the cost, saying scanning "does not require Google Play services, but the model increases your app size by a few megabytes."

The fullscreen scan(...), the embedded startScan(...) and readBarcodesFromImage(...) all run on that model, so there is no Play services branch to write. The scanner UI ships inside the plugin rather than as a Play services module, which is why the plugin's migration table marks isGoogleBarcodeScannerModuleAvailable() as "Not needed". isAvailable() only checks whether the device has a camera. The plugin declares the camera permission in its own manifest, so neither the DEPENDENCIES meta-data nor any other manifest change is required. On iOS, the plugin is built on AVFoundation and Vision only, with no third-party pods.

A fullscreen scan with a themed UI takes one call:

import { BarcodeFormat, BarcodeScanner } from '@capawesome-team/capacitor-barcode-scanner';

const scanParcelLabel = async () => {
  const { barcodes } = await BarcodeScanner.scan({
    formats: [BarcodeFormat.Code128, BarcodeFormat.DataMatrix],
    ui: {
      accentColor: '#ff9500',
      beep: true,
      instructions: 'Hold the label inside the frame.',
      title: 'Scan Parcel',
    },
  });
  return barcodes[0].rawValue;
};

Nothing in this call goes through Play services, so the code path is the same on a Pixel, a Huawei phone and an AOSP handheld. For scanning inside your own layout, Embedded Barcode Scanner with Camera Preview in Capacitor covers the embedded startScan() mode with a native camera preview. The plugin is part of the paid Capawesome Insiders subscription, and the Installation section of the plugin documentation covers the setup.

Which one to pick

Choosing between the two plugins depends on whether any device that runs your app lacks Play services, who builds the scanner UI, and whether a subscription fits your project. The three paths compare as follows:

Path	Needs Google Play services	UI	Camera permission	Price
ML Kit plugin, `startScan()`	No	Your own, behind the web view	Yes	Free
ML Kit plugin, `scan()`	Yes, on Android	Google code scanner	Not on Android	Free
Barcode Scanner plugin, all methods	No	Themeable fullscreen UI or embedded native preview	Yes, declared by the plugin	Insiders subscription

Both bundled paths make the app larger by the amount in Google's table above. The scan() path keeps the app smaller, but it depends on Play services and on the module download before its first use. On devices that have Play services, it is also the shortest path, since there is no UI to build. Apps that read Wi-Fi codes, contact cards or driver licenses should factor in the ML Kit plugin's structured payload parsing.

FAQ

Does Capacitor barcode scanning work without Google Play services?

Yes, when the Android side uses the bundled ML Kit model, which is linked into the app at build time. The free Capacitor ML Kit Barcode Scanning plugin uses it for startScan() and readBarcodesFromImage(), and the Capacitor Barcode Scanner plugin uses it for every method. Only the ML Kit plugin's scan() needs Google Play services, because it runs the Google code scanner.

Does the ML Kit plugin work on Huawei devices?

Yes, with startScan(). Our answer on GitHub is that "Huawei devices are supported but you have to use the startScan(...) method and build the UI yourself." The ready-made scan() screen comes from Google Play services, which Huawei phones released after May 2019 don't have.

How much does the bundled model add to the app size?

Google puts the bundled barcode model at "About 2.4 MB size increase", compared to "About 200 KB size increase" for the unbundled variant. The Capacitor Barcode Scanner plugin's documentation describes the same cost as "a few megabytes".

Do I still need the `DEPENDENCIES` meta-data?

Only if you use the ML Kit plugin's scan(). The barcode_ui value from the plugin's setup asks Google Play services to download the Google code scanner module while the app is installed from the Play Store; without it, Play services downloads the module the first time the scanner runs. The meta-data has no effect on startScan() and does nothing on devices without the Play Store. The Capacitor Barcode Scanner plugin needs no manifest changes at all.

Does barcode scanning work offline?

Yes, once the model is on the device. Google's ML Kit overview states that ML Kit processing happens on-device and "also works while offline". A bundled model is available from installation, while the unbundled model and the Google code scanner module have to be downloaded through Play services before their first use. On iOS, both plugins work offline, since the ML Kit iOS SDK comes as a pod with no Play services variant and the Capacitor Barcode Scanner plugin uses AVFoundation and Vision.

Is the Capacitor Barcode Scanner plugin free?

No. It's part of the paid Capawesome Insiders subscription, which covers all Insiders plugins and priority support. The Capacitor ML Kit Barcode Scanning plugin and the Capacitor Google Play Services plugin are free.

Try Capawesome Cloud

One Android build can go to both Google Play and Huawei AppGallery through Capawesome Cloud destinations. The Huawei AppGallery destination uploads the build to AppGallery Connect and, depending on the release status, submits it for review.

Try Capawesome Cloud Free

Conclusion

Use the bundled model as soon as one device that runs your app ships without Google Play services. On the free plugin, that means startScan() with your own UI and a getStatus() check deciding where scan() is safe. If you'd rather not build and maintain a scanner screen, the Capacitor Barcode Scanner plugin gives you the fullscreen UI and the embedded view on the bundled model. Keep scan() alone only when every device is Google-certified. To ship the same build to Huawei users, read Publish a Capacitor App on Huawei AppGallery.

If you have any questions, join us on the Capawesome Discord server. To stay updated on the latest news, subscribe to the Capawesome newsletter.

MapLibre vs. Google Maps: Which Map SDK to Use?

Robin — Thu, 01 Oct 2026 15:30:27 +0000

Originally published on the Capawesome blog.

MapLibre is a free, open-source map renderer that draws tiles from a provider you choose, while Google Maps is a data platform billed per SKU once a free monthly cap runs out. That makes MapLibre vs. Google Maps a decision about data more than rendering. Pick Google when your app needs its places, Street View or traffic, and MapLibre when the map shows your own points, routes and areas. This post compares 2026 pricing, the map ID billing trap, tile costs, terms, rendering, offline support and search, with a Capacitor focus on @capacitor/google-maps and the free Capacitor MapLibre plugin. The Capacitor MapLibre plugin is built and maintained by Capawesome and is not affiliated with or endorsed by the MapLibre organization.

Key takeaways:

Google Maps Platform has no base fee; since March 1, 2025, each SKU has a free monthly cap of 10,000 (Essentials), 5,000 (Pro) or 1,000 (Enterprise) events.
Native map loads on Android and iOS are free and unlimited only without a map ID; with one, they bill as Dynamic Maps at $7.00 per 1,000 after 10,000.
The MapLibre renderer and the Capacitor MapLibre plugin are free; 1.5 million tile requests a month cost $0 on OpenFreeMap and $500 on CARTO's commercial plan.
Google's terms forbid tile caching and Places content on non-Google maps; EEA terms since July 8, 2025 lift the non-Google-map rule but bar Places API content from any map.
MapLibre Native supports offline regions through OfflineManager on Android and MLNOfflineStorage on iOS, but the Capacitor MapLibre plugin does not expose them yet.
MapLibre itself has no Street View, traffic layer, indoor data or places database, so the data your app needs decides the choice more than the price does.

Renderer vs. platform

MapLibre is a rendering engine without map data of its own. The MapLibre organization maintains MapLibre GL JS for browsers and MapLibre Native for Android, iOS and desktop, both forked from Mapbox's libraries before Mapbox moved them to a non-open-source license in December 2020. A charter governs the project through a five-person board on which no single company may hold more than one seat, and sponsors include Amazon Web Services, Microsoft and MapTiler. A style document following the MapLibre Style Spec decides where the tiles, fonts and sprites come from.

Google Maps Platform sells three layers under one account: the rendering SDKs (Maps SDK for Android and iOS, Maps JavaScript API), Google's map data, and web services such as Places, Routes and Geocoding. Each of them requires a billing-enabled Cloud project and an API key, on mobile as well as on the Web.

The Capacitor plugins mirror that split. @capacitor/google-maps wraps the Google rendering SDKs and has no API for Street View, Places or Directions, which remain separate Google Maps Platform services. The Capacitor MapLibre plugin wraps MapLibre Native on Android and iOS and MapLibre GL JS on the Web, where maplibre-gl has been an optional peer dependency since plugin version 0.2.0. With MapLibre, the data source is a separate decision, and most of this comparison is about it.

Google Maps pricing

Google Maps Platform has no monthly base fee in 2026. Every billable event, such as a map load or an autocomplete request, belongs to a SKU with a free monthly cap, and you pay a listed price per 1,000 events above that cap. Optional subscriptions from $100 a month swap this for a fixed price, and native mobile map loads without a map ID cost nothing at any volume.

Since March 1, 2025, the free cap depends on the SKU category and replaces the former $200 monthly credit:

Essentials: 10,000 events per month
Pro: 5,000 events per month
Enterprise: 1,000 events per month

These are the SKUs a typical map screen triggers, with first-tier prices in USD from Google's pricing page as of September 2026:

SKU	Free per month	Price per 1,000	Triggered by
Maps SDK	Unlimited	$0	Native map load without a map ID
Dynamic Maps	10,000	$7.00	Web map load, native map load with a map ID
Dynamic Street View	5,000	$14.00	Street View panorama
Autocomplete Requests	10,000	$2.83	Search box request
Place Details Essentials / Pro / Enterprise	10,000 / 5,000 / 1,000	$5.00 / $17.00 / $20.00	Place details lookup
Geocoding	10,000	$5.00	Address to coordinates
Compute Routes Essentials	10,000	$5.00	Route request (Routes API)

Zooming and panning do not create extra billable events. Above 100,000 events a month, prices drop in volume tiers that count usage across all projects on a billing account; Dynamic Maps falls to $5.60 per 1,000 up to 500,000 loads. Calculated from these list prices, a month of web map loads costs:

50,000 loads: $280
100,000 loads: $630
250,000 loads: $1,470

The optional subscriptions launched on November 5, 2025 and put all included SKUs under one combined monthly call limit:

Starter: $100 per month for 50,000 calls, Dynamic Maps and Geocoding only
Essentials: $275 per month for 100,000 calls
Pro: $1,200 per month for 250,000 calls, adding Pro SKUs such as Place Details Pro

Starter covers the 50,000-load month above for $100 instead of $280. Google does not block calls beyond a plan's limit and bills the overage at pay-as-you-go prices, while free SKUs such as Maps SDK don't count toward it. New customers get a $300 trial credit that expires after 90 days. The Maps Demo Key skips billing details, but Google limits it to prototyping and documents it for the Maps JavaScript API and web services only.

The map ID trap

A map ID moves native map loads from the free Maps SDK SKU to Dynamic Maps. Google's SKU definition counts an Android or iOS map load as Maps SDK only when the map is "not loaded with a map ID". @capacitor/google-maps has accepted androidMapId and iOSMapId since version 5.4.0, and cloud-based map styling needs them. With a map ID set, native map loads on that platform draw from the Dynamic Maps cap of 10,000 and cost $7.00 per 1,000 after that.

For an app with 100,000 native map loads a month, that is the difference between $0 and $630, calculated from the list prices.

Styling without a map ID goes through the plugin's styles option, which takes JSON map styles. Issue #96, open since August 2025, reports that styles cannot be set when a map ID is present, so the two approaches don't combine. Unlimited mobile map loads therefore hold only for maps without a map ID, which rules out cloud-based styling.

The Web has no such exception. The Maps JavaScript API bills every load as Dynamic Maps with or without a map ID, and the plugin's web implementation assigns a map ID automatically when you don't pass one.

MapLibre tile costs

The Capacitor MapLibre plugin is free under the MIT license and needs no API key, so the running cost of a MapLibre map is whatever the tile provider charges. createMap(...) takes a style URL, and the style points the map at the provider's tiles, fonts and sprites. This example uses OpenFreeMap, which needs no key and no registration:

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

await MapLibre.createMap({
  mapId: 'stores',
  elementId: 'map',
  styleUrl: 'https://tiles.openfreemap.org/styles/liberty',
  center: { latitude: 52.52, longitude: 13.405 },
  zoom: 11,
});

The returned promise resolves after the Liberty style has loaded from OpenFreeMap, with no account or key involved. Moving to another provider later means a different styleUrl, as long as the new style follows the MapLibre Style Spec. These are the main options as of September 2026:

Provider	Free tier	Paid	Key
OpenFreeMap	No request limits	None, donation-funded	No
Versatiles	Free, self-hostable	None, donation-funded	No
CARTO basemaps	1M requests/month commercial, 5M non-commercial	$500/month up to 10M	Yes, free
MapTiler Cloud	100k requests/month, non-commercial	Flex $30/month for 500k, then $0.15 per 1,000	Yes
Stadia Maps	200k credits/month, non-commercial	Starter $20/month for 1M credits, then $0.03 per 1,000	Yes
Protomaps on Cloudflare R2	R2 free tier	Workers $5/month incl. 10M requests	No, own URL
Amazon Location Service	500k tiles/month for 3 months, new customers	$0.04 per 1,000 tiles	Yes
Mapbox vector tiles	200k requests/month	$0.25 per 1,000	Yes, access token

CARTO has required a free API key since 2026 and may watermark tiles requested without one. MapTiler's free plan requires the MapTiler logo and suspends maps for the rest of the month at the limit, and MapTiler bills MapLibre usage by request because sessions only apply to its own SDK. Mapbox's guide to using its tiles with MapLibre covers GL JS only. Protomaps packs the whole basemap into one archive that you host yourself, though its docs warn that R2 is known to have higher latency.

To compare costs, assume 100,000 map views a month at 15 vector tiles per view. The 15-tile figure is how Jawg and Azure Maps define a map view, not a measurement of a Capacitor app. The resulting 1.5 million tile requests cost, calculated from the list prices above:

OpenFreeMap or Versatiles: $0
Stadia Maps Starter: $35
Amazon Location Service, after the free period: $60
MapTiler Flex: $180
Mapbox vector tiles: $325
CARTO commercial plan: $500

The same 100,000 views as Google web map loads come to the $630 from the pricing section, and to nothing as native Google map loads without a map ID. OpenFreeMap offers no SLA and no support, so an app that depends on its map should keep a paid provider or a self-hosted archive as the fallback.

Terms and lock-in

Google's Maps Platform Terms, last modified August 26, 2026, contain four rules that shape any map feature:

3.2.2(b) Attribution: show all attribution Google provides, without modifying, obscuring or deleting it.
3.2.3(a) No scraping: no pre-fetching, storing or bulk downloading of Google Maps content, map tiles included.
3.2.3(b) No caching: only where the Maps Service Specific Terms allow it, and they grant nothing for map tiles.
3.2.3(e) No use with non-Google maps: Google Maps Core Services may not be used with or near a non-Google map, which covers Places content on one and Street View on the same screen.

Rule 3.2.3(e) is where the lock-in sits. Once an app shows Places results next to a Google map, switching the renderer means replacing the search as well.

Since July 8, 2025, projects linked to EEA billing accounts can fall under separate EEA terms. According to Google's EEA FAQ, those terms remove the non-Google-map rule, but content from the Places API may no longer be displayed with any map, a Google map included. The Places UI Kit takes its place and works with third-party maps.

The MapLibre side has obligations too. OpenStreetMap data, the base of most free tiles, is licensed under the ODbL, which requires visible credit to OpenStreetMap and its contributors and puts altered data you distribute under the same license. Make sure your map screen shows that credit and whatever your tile provider asks for. OSM's own tile server is not meant as a production basemap, since its tile policy promises best-effort availability without an SLA and blocks generic user agents. Lock-in on this side stays low, because the Style Spec is an open format and leaving a provider means pointing at another style rather than rewriting the map.

Rendering

Both Capacitor plugins draw a native map view on Android and iOS. The differences sit in the rendering backends and in how that view shares the screen with the web view.

MapLibre Native replaced OpenGL ES with Metal on iOS in version 6.0.0, released January 16, 2024. On Android, Vulkan support arrived in 11.7.0 and became the default backend of the android-sdk package in 13.0.0. The Capacitor MapLibre plugin uses the org.maplibre.gl:android-sdk-vulkan-opengl artifact, version 13.5.0 by default, which switches between OpenGL and Vulkan at runtime. MapLibre renders any style JSON that follows the Style Spec, setStyle(...) swaps it while the app runs, and the Maputnik editor edits styles visually. The Google Maps SDKs offer the map types normal, hybrid, satellite and terrain, plus the two styling paths from the map ID section.

Inside a Capacitor app, the layering differs per plugin. @capacitor/google-maps renders beneath the web view on Android only; on iOS it renders the map directly into the web view, so no transparency is needed there. The Capacitor MapLibre plugin renders behind the web view on Android and iOS, so the map element and its ancestors need transparent backgrounds on both platforms. A Google Maps Alternative for Capacitor Apps walks through that transparency setup.

Globe view and 3D terrain exist in MapLibre GL JS, which added globe mode in version 5.0.0. Neither is in a released MapLibre Native version yet, and native globe support is still an open issue. On the Web, GL JS has required WebGL2 since version 6.0.0, which dropped WebGL1.

Offline maps

Google's terms leave no room for offline maps in your app. The no-caching and no-pre-fetching rules in section 3.2.3 forbid storing tiles, @capacitor/google-maps has no offline API, and a closed issue titled "Map goes blank when internet connection is lost" shows what users see without a connection.

MapLibre Native supports offline maps at the SDK level. On Android, OfflineManager lists and creates offline regions and downloads the resources they need. On iOS, MLNOfflineStorage manages offline packs and ambient caching. The Capacitor MapLibre plugin does not expose either API yet, as its FAQ notes: "Offline tile management is not part of this version of the plugin." Styles, fonts, sprites and tiles load from the network.

Any offline storage also has to respect the tile provider's terms. CARTO's basemap terms forbid on-device caching beyond 30 days, and OSM's tile policy forbids apps from offering prefetch features. OpenFreeMap publishes weekly planet downloads, including MBTiles, for teams that want to host the tiles themselves.

Data and search

Google's advantage is its data. Its December 2024 pricing announcement describes a map with information on over 250 million businesses and places. The Google Maps SDKs add Street View, a live traffic layer (enableTrafficLayer in the Capacitor plugin), indoor floor plans (enableIndoorMaps) and satellite imagery as a built-in map type. MapLibre has no equivalent for Street View, traffic or indoor data. Satellite imagery depends on the provider, for example MapTiler Satellite, Stadia Maps from its Standard plan, or the free Versatiles orthophotos.

The open alternatives come with open licenses. OpenStreetMap data falls under the ODbL described in the terms section. Overture Maps publishes its base, buildings, divisions and transportation themes under the ODbL as well, while its places theme mixes sources under CDLA Permissive 2.0, Apache 2.0 (Foursquare) and CC0 (AllThePlaces).

Search needs a separate service, because MapLibre ships no Places API. These services fill the gap:

Nominatim: the public OpenStreetMap geocoder allows an absolute maximum of 1 request per second and forbids client-side autocomplete, so it suits occasional lookups, not a search box.
MapTiler and Stadia Maps: both sell geocoding next to their tiles, and MapTiler includes 1,000 free search sessions a month.
Native geocoding: the Capacitor Geocoder plugin, part of the paid Capawesome Insiders subscription, uses the platform geocoder on Android and iOS without an API key and offers Google Maps or OpenStreetMap as providers on the Web.

Outside the EEA, section 3.2.3(e) rules out showing Google geocoding or Places results on a MapLibre map. The same applies to results from the Geocoder plugin's Google Maps provider on the Web.

Which to pick

The MapLibre vs. Google Maps choice follows the data your screens need, with cost as the tiebreaker.

Your app needs	Pick	Reason
Street View, live traffic or indoor maps	Google Maps	No MapLibre equivalent
Places search or Directions already in use	Google Maps	3.2.3(e) ties Places to a Google map outside the EEA
A native-only map with Google data, no cloud styling	Google Maps	Map loads stay free without a map ID
Your own points, routes and areas	MapLibre	Any Style Spec tile provider works
No billing account, e.g. open-source or client apps	MapLibre	The plugin needs no key
A high-traffic web map	MapLibre	1.5M tiles cost $0 to $500, Google web loads $630
Cloud-styled native maps at volume	MapLibre	A map ID bills native loads as Dynamic Maps
Place details next to a map in the EEA	Places UI Kit, on either map	EEA terms bar Places API content from any map

On mobile, a Google map without a map ID costs nothing to load, so price alone rarely justifies a switch there. On the Web and with cloud styling, Google bills every load above the free cap, and at 100,000 views a month every provider in the tile comparison costs less.

FAQ

How much does Google Maps cost per month in 2026?

There is no base fee. Every SKU has a free monthly cap, and you pay a listed price per 1,000 events above it, such as $7.00 for web map loads after the first 10,000. Native map loads without a map ID stay free at any volume. Optional subscriptions start at $100 a month for 50,000 calls. Apart from the prototyping-only Demo Key, every setup needs a billing-enabled Cloud project.

Is MapLibre free to use commercially?

Yes. MapLibre GL JS is licensed under BSD-3-Clause and MapLibre Native under BSD-2-Clause, and the Capacitor MapLibre plugin is MIT-licensed. Tile providers set their own rules. OpenFreeMap allows commercial use, while the free tiers of MapTiler and Stadia Maps exclude it.

Do I need an API key to use MapLibre?

Not for MapLibre or the Capacitor MapLibre plugin. The tile provider may need one. OpenFreeMap and Versatiles work without a key, CARTO issues a free one, and MapTiler, Stadia Maps and Amazon Location Service require their own. The plugin's default demo style is meant for testing, not production.

Can I show Google Places results on a MapLibre map?

Not outside the EEA, where section 3.2.3(e) of Google's terms forbids displaying Places content on a non-Google map. Projects under the EEA terms lose that rule, but Places API content may then not be displayed with any map. For those projects, Google offers the Places UI Kit, which works with any map, MapLibre included.

Does MapLibre work offline in a Capacitor app?

Not yet. MapLibre Native can download offline regions, but the Capacitor MapLibre plugin does not expose that API, so styles and tiles load from the network. Google Maps is no alternative here, because its terms forbid caching and pre-fetching tiles.

Can I migrate from @capacitor/google-maps to MapLibre?

Yes for the map itself, but plan for what surrounds it. Outside the EEA, Places search and Google geocoding have to move to another provider together with the map. Clustering has no counterpart in the Capacitor MapLibre plugin, and satellite or terrain views need a tile provider that serves them. A Google Maps Alternative for Capacitor Apps shows the MapLibre side of markers, polylines and the camera.

Stay in the loop

New plugins and releases, including updates to the Capacitor MapLibre plugin, go out in the Capawesome newsletter first.

Subscribe to the Capawesome Newsletter

Conclusion

Start from the list of Google data your screens show. If it includes Street View, live traffic, indoor maps or Places results beside the map, use Google Maps, keep native maps free by leaving out the map ID, and estimate the remaining SKUs before launch. If the list is empty, use MapLibre with a tile provider from the table and budget for tile requests instead of map loads. For apps that record the routes they draw, Announcing the Capacitor Background Geolocation Plugin covers the tracking side.

If you have any questions, join us on the Capawesome Discord server. To stay updated on the latest news, subscribe to the Capawesome newsletter.

How to Scan a Document to PDF in a Capacitor App

Robin — Wed, 30 Sep 2026 15:31:59 +0000

Originally published on the Capawesome blog.

A signed contract that comes out of a scanner as a folder of JPEGs is hard to email, print or file, so most apps want one PDF instead. The Capacitor Document Scanner plugin returns that PDF next to the individual page images when you pass generatePdf: true to scanDocument(...). This guide shows how to scan a document to PDF in a Capacitor app and what to do with the file afterwards, from opening it in a native viewer to printing it, sharing it and keeping it past the next app launch. The scanner and the Capacitor Printer plugin are part of Capawesome Insiders; the PDF viewer, the file opener and the official Share and Filesystem plugins are free.

Key takeaways:

scanDocument({ generatePdf: true }) returns one combined PDF in pdf and still returns every page as a JPEG in scannedImages, from the same scan.
On Android, Google's ML Kit generates the PDF; on iOS, VisionKit returns only page images, and the plugin composes an image-only PDF from them.
The pdf value is a file URL in the app's cache that the PDF Viewer, Printer, File Opener and @capacitor/share plugins accept without conversion.
pageLimit defaults to 10 and caps the PDF as well, so raise it for longer documents; on iOS, extra pages are dropped after scanning.
The Capacitor Document Scanner plugin clears its cache files when it loads on the next app launch, so copy the PDF to Directory.Data in the same flow.

One PDF per scan

To turn scanned pages into a single PDF in Capacitor, call scanDocument(...) of the Capacitor Document Scanner plugin with generatePdf: true. The result then holds one combined PDF of all scanned pages in pdf, and the pages themselves as JPEG files in scannedImages. The plugin is part of Capawesome Insiders. To install it, please refer to the Installation section in the plugin documentation, and do the same for each companion plugin below. Announcing the Capacitor Document Scanner Plugin covers setup and the Android scanner options, so this guide starts at the scan call:

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

const scanToPdf = async () =&gt; {
  try {
    const { pdf, scannedImages } = await DocumentScanner.scanDocument({
      generatePdf: true,
    });
    return { pdf, scannedImages };
  } catch (error) {
    if ((error as { code?: string }).code === 'SCAN_CANCELED') {
      return null;
    }
    throw error;
  }
};

When the user backs out of the scanner, the promise rejects with the SCAN_CANCELED error code. That is a normal outcome, so the function returns null instead of throwing. pdf is typed string | null because it is only set when generatePdf is true; the snippets in the following sections take it as a string.

The two platforms produce the PDF differently. On Android, ML Kit generates it. Google's Android guide states that the scanner can return both PDF and JPEG files for a scan, depending on the formats an app requests with setResultFormats, and it recommends requesting only the formats you need, since generating document files takes time and processing power. The scanner itself is a Google Play services module rather than part of your APK. Google lists its app size impact as a "~300KB download size increase", and it only runs on devices with Play services, which is what isAvailable() checks on Android.

On iOS, Apple's VNDocumentCameraViewController returns page images and no PDF. Apple leaves the export to the app: "With the collection of scanned images, your app can create a digital version of the physical document and export the scanned images to PDF." The plugin does that export with one PDF page per scanned page, and the result is an image-only PDF without a text layer.

Page limit and quality

The pageLimit option caps the PDF along with the images. It defaults to 10, so a 14-page contract never fits into one PDF with default options. Raise the limit for long documents:

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

const scanContract = async () =&gt; {
  const { pdf } = await DocumentScanner.scanDocument({
    generatePdf: true,
    pageLimit: 30,
  });
  return pdf;
};

On Android, ML Kit enforces the limit inside the scanner UI. VisionKit has no public API to stop the scanner after a set number of pages, so on iOS the plugin truncates the result after scanning, and the pages past the limit are missing from the PDF as well. Set pageLimit above the longest document your users handle, or mention the limit in your own UI before the scanner opens.

The imageQuality option does not shrink the PDF. It re-encodes only the JPEG pages and leaves the PDF untouched on both platforms, and the plugin has no option for the PDF's page size, resolution or compression. Lower imageQuality when you store or upload the JPEGs, not to make pdf smaller.

Open the PDF in-app

The Capacitor PDF Viewer plugin shows the scanned PDF in a fullscreen native viewer with a toolbar, paging and pinch-to-zoom, without the user leaving your app. It is free. Pass the scanner's pdf value as path to open(...):

import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const openScan = async (pdf: string) =&gt; {
  await PdfViewer.open({
    path: pdf,
    title: 'Rental contract',
    showShareButton: true,
  });
};

Always pass a title. The viewer falls back to the file name, and the scanner names its files with a generated ID, not with anything a user would recognize. showShareButton adds a share button to the viewer toolbar on Android and iOS; on Android, it depends on the same file provider setup as the Share plugin (see Share or hand off).

The viewer renders differently per platform. On iOS, the plugin uses Apple's PDFKit and needs no configuration. On Android, it uses the android-pdf-viewer library, which bundles the Pdfium native libraries and adds about 10 to 16 MB (uncompressed, across all ABIs) to your app. Published as an Android App Bundle, each device downloads only the libraries for its own ABI. The Android viewer does not support text selection.

Print the PDF

The Capacitor Printer plugin prints the scanned PDF with printPdf(...), which presents the platform's printing UI on Android and iOS. Like the scanner, it is a Capawesome Insiders plugin.

import { Printer } from '@capawesome-team/capacitor-printer';

const printScan = async (pdf: string) =&gt; {
  await Printer.printPdf({
    name: 'Rental contract',
    path: pdf,
  });
};

name sets the name of the print job and defaults to Document, so pass the same label you gave the viewer. The Printer plugin can print the scanned images as well, for example through printFile(...), when the user needs a single page rather than the whole document. Exploring the Capacitor Printer API covers the remaining print methods, from base64 data to HTML.

Share or hand off

The free @capacitor/share plugin from the Capacitor team opens the platform's share sheet, so the user can send the PDF to another app, such as a mail client or a messenger. Its files option takes an array of file:// URLs on Android and iOS, and the scanner's pdf value is such a URL:

import { Share } from '@capacitor/share';

const shareScan = async (pdf: string) =&gt; {
  await Share.share({
    title: 'Rental contract',
    files: [pdf],
  });
};

title becomes the subject when the user shares to email. If the user closes the sheet without picking an app, share() rejects with the message Share canceled, which deserves the same handling as a canceled scan.

Sharing the scanned PDF on Android needs no configuration. The Share documentation gives the reason:

> By default, Capacitor apps only allow to share files from caches folder. To make other Android folders shareable, they have to be added in android/app/src/main/res/xml/file_paths.xml file.

The scanner writes to that cache folder, and the file_paths.xml of a default Capacitor app already declares it with a `` entry. The PDF Viewer share button and the File Opener plugin pass files to other apps through the same file provider, so they work on the cached PDF without changes too.

To open the PDF in another app rather than send it, use the free Capacitor File Opener plugin. openFile(...) determines the MIME type on its own:

`typescript
import { FileOpener } from '@capawesome-team/capacitor-file-opener';

const openInDefaultApp = async (pdf: string) => {
await FileOpener.openFile({ path: pdf });
};
`

On iOS, the call shows a Quick Look preview inside your app, with the system share button. On Android, it opens the PDF in the user's default PDF app, or shows the app chooser if no default is set. Compared with the PDF Viewer plugin, File Opener leaves the choice of viewer to the platform, while the PDF Viewer plugin lets you set the title and the initial page and listen for page changes.

Keep the PDF

The Capacitor Document Scanner plugin writes the PDF to the app's cache directory and deletes it again on the next app launch. From the plugin's FAQ:

> 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.

The official @capacitor/filesystem plugin, which is free, copies the PDF to a persistent directory:

`typescript
import { Directory, Filesystem } from '@capacitor/filesystem';

const keepScan = async (pdf: string) => {
const { uri } = await Filesystem.copy({
from: pdf,
to: 'contract.pdf',
toDirectory: Directory.Data,
});
return uri;
};
`

Without a directory option, the Filesystem plugin reads from as a full file:// path, and toDirectory places the copy in Directory.Data, which is the app's files directory on Android and the Documents directory on iOS. Files there are deleted when the app is uninstalled, not on the next launch. copy(...) resolves with the uri of the copy, which you store with the document record. Give every document its own file name, since a fixed name like contract.pdf only fits one.

The Capacitor File Manager plugin, an Insiders plugin, does the same with copyFile(...), which copies natively with constant memory usage and takes file:// URIs throughout its API. Android Scoped Storage in Capacitor Apps, Explained compares the directories an Android app can write to without a permission. On iOS, the Filesystem documentation lists two Info.plist keys, UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace, that make the app's files appear in the Files app when set to YES.

Moving the PDF out of the cache has one consequence on Android. The app's files directory is not in Capacitor's default file_paths.xml, so the Share plugin, the File Opener plugin and the PDF Viewer share button cannot pass the copy to another app until you declare it. Add a ` entry to android/app/src/main/res/xml/file_paths.xml`:

The first two entries are the Capacitor defaults, and `` adds the app's files directory.

If the scan goes to a backend instead of staying on the device, the Capacitor File Transfer plugin, also an Insiders plugin, uploads files in the background; Announcing the Capacitor File Transfer Plugin walks through it.

FAQ

How do I turn scanned pages into a single PDF in Capacitor?

Call scanDocument(...) of the Capacitor Document Scanner plugin with generatePdf: true. The result contains one combined PDF in pdf and the page images in scannedImages. ML Kit generates the PDF on Android, the plugin composes it from the VisionKit page images on iOS, and it holds at most pageLimit pages (default 10).

Is the scanned PDF searchable?

The Capacitor Document Scanner plugin runs no OCR, and on iOS the PDF has no text layer. If you need the text of a document, run processImage(...) of the free Capacitor ML Kit Text Recognition plugin on the JPEG pages in scannedImages.

Does scan-to-PDF work on the web?

No. scanDocument(...) rejects with an unimplemented error on the web. The PDF Viewer plugin has no web implementation either, since browsers display a PDF in an `

How to Use Gemini Nano in a Capacitor App

Robin — Tue, 29 Sep 2026 15:30:33 +0000

Originally published on the Capawesome blog.

Gemini Nano is Google's on-device language model for Android, and a Capacitor app can prompt it without an API key, a server or a per-request bill. The Capacitor LLM plugin runs it through AICore, the Android system service that manages the model on supported phones. This guide to Gemini Nano in a Capacitor app walks through the device list, the availability check, the model download with a determinate progress bar, text generation and streaming, and the quota and foreground rules that AICore enforces. The plugin is part of Capawesome Insiders, a paid subscription. If you only need summaries, proofreading or rewriting on Android, the free Capacitor ML Kit GenAI plugins cover those tasks, and a later section compares the two options.

Key takeaways:

AICore stores one shared copy of Gemini Nano per device, so the model can already be available before your app downloads anything.
The Capacitor LLM plugin's getAvailability() never rejects and reports four statuses on Android: available, downloadable, downloading and unavailable.
During downloadModel(), the downloadProgress event reports a value between 0 and 1, so the download can drive a determinate progress bar.
AICore answers too many requests with a BUSY quota error that calls for exponential backoff, and allows inference only while your app is the top foreground app.
Prompt API devices include the Pixel 9, Pixel 10, Galaxy S26 and OnePlus 15, and each needs API level 26 or higher and a locked bootloader.

How Gemini Nano runs

Gemini Nano runs inside AICore, which Google describes as "an Android system service that enables on-device execution of GenAI foundation models". Your app never ships the model, because AICore handles its distribution and its updates. Apps reach it through Google's ML Kit GenAI APIs, which come in two kinds:

Prompt API: takes free-form prompts. This is the API the Capacitor LLM plugin calls on Android.
Feature-specific APIs: Summarization, Proofreading, Rewriting and Image Description each handle one fixed task. A sixth API covers speech recognition.

Google offers the Prompt API and the four feature-specific APIs as beta, "not subject to any SLA or deprecation policy", and Speech Recognition as alpha. The Prompt API moved from alpha to beta on January 28, 2026.

Because the APIs run on the device, Google states that input, inference and output data are processed locally and that the features keep working without a reliable internet connection. Prompts and responses stay on the device. Google's ML Kit GenAI terms still require you to inform users about Google's processing of metrics data, so cover that in your privacy policy. According to Google's July 2026 Android Developers blog post, Gemini Nano now runs on over 140 million devices.

The Capacitor LLM plugin exposes the Prompt API to your web code through one TypeScript interface. It is part of Capawesome Insiders, a paid subscription. To install the Capacitor LLM plugin, please refer to the Installation section in the plugin documentation.

Supported devices

Gemini Nano runs only on the devices Google lists for each ML Kit GenAI API, and the Prompt API device list is the one that applies to the Capacitor LLM plugin. It names phones and tablets from 14 brands and groups them by the Nano version each device runs:

Gemini Nano version	Example devices
nano-v2	OnePlus 13, Xiaomi 15, Galaxy Z Fold7, Honor Magic 7, realme GT 7 Pro
nano-v3	Pixel 9 and Pixel 10 (including Pro, Pro XL and Pro Fold), Galaxy S26 series, OnePlus 15, OPPO Find X9, vivo X300
nano-v4	Pixel 11 (including Pro, Pro XL and Pro Fold), Galaxy Z Flip8, Galaxy Z Fold8

The version affects the output. Google notes that "different versions of Gemini Nano may return different output from the same prompt", so a prompt tuned on a Pixel 10 needs a second look on a nano-v2 phone such as the Xiaomi 15.

Every device on the list also has to meet the requirements Google repeats on each API page. It must run Android API level 26 or higher, and the APIs are not supported on devices with an unlocked bootloader. Google names MediaTek Dimensity, Qualcomm Snapdragon and Google Tensor as the supported chip platforms.

On iOS, the same plugin talks to Apple Intelligence instead, and How to Use Apple Intelligence in a Capacitor App covers that side.

Check availability

The Capacitor LLM plugin reports whether Gemini Nano is ready with getAvailability(), a method that never rejects. On the web, or anywhere else without a system model, it resolves with unavailable, so you can call it unconditionally at startup. Android reports four of the plugin's statuses:

Status	Meaning on Android	What the screen shows
`available`	The model is downloaded and ready.	The feature.
`downloadable`	The device supports Gemini Nano, but the model is not on it yet.	A download button.
`downloading`	A download is running.	A waiting indicator.
`unavailable`	Gemini Nano cannot run on this device right now.	Nothing, or a fallback.

The following function turns the status into one of four UI states and keeps it current. It reads the status once, then subscribes to the availabilityChange event, which fires when the status changes, for example when a download completes:

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

type AssistantState = 'ready' | 'needs-download' | 'downloading' | 'hidden';

const toAssistantState = (status: AvailabilityStatus): AssistantState =&gt; {
  switch (status) {
    case 'available':
      return 'ready';
    case 'downloadable':
      return 'needs-download';
    case 'downloading':
      return 'downloading';
    default:
      return 'hidden';
  }
};

const observeAssistantState = async (onChange: (state: AssistantState) =&gt; void) =&gt; {
  const { status } = await Llm.getAvailability();
  onChange(toAssistantState(status));
  return Llm.addListener('availabilityChange', event =&gt; {
    onChange(toAssistantState(event.status));
  });
};

The plugin watches the status only while at least one listener is attached, so call remove() on the returned handle when the screen closes. The default branch covers unavailable as well as the statuses that only iOS reports.

Download the model

Gemini Nano has to be downloaded to the device before a Capacitor app can use it, but the download may already have happened. AICore keeps one shared copy of the model for all apps on the device, so if another app triggered the download earlier, getAvailability() reports available and your app can skip this step. The four feature-specific ML Kit APIs also fetch a small adapter model per feature on top of that shared base model.

When the status is downloadable, downloadModel() starts the download and resolves once it completes. Along the way, the downloadProgress event reports progress as a value between 0 and 1, which maps directly onto a `` element. Google publishes no download size, and its Firebase documentation says the download time "depends on many factors, including your network", so show the bar instead of a spinner.

Start the download from a clear user action, such as an "Enable reply drafts" button, and offer it before the user reaches the screen that needs the model:

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

const enableReplyDrafts = async () => {
showProgressBar(0);
try {
await downloadGeminiNano(showProgressBar);
showReplyDrafts();
} catch {
showRetryButton();
}
};
`

The screen can also open in the downloading state. That happens when your app started the download in an earlier session, or when another app started it. Show an indeterminate indicator in that case, and let the availabilityChange listener from the previous section switch the screen to ready once the status turns available.

On a supported phone, unavailable is not always final. After a device is set up or reset, AICore first has to download its configuration, and Google's setup notes say that this "usually takes a few minutes to a few hours" while the device is online. Check the status again on the next app start instead of hiding the feature for good. If downloadModel() itself rejects, the retry button above covers it. Google's advice for network errors during a download is to keep the connection, wait a few minutes and retry.

Generate and stream

Text generation in the Capacitor LLM plugin happens inside a chat, which carries instructions (the system prompt) and the conversation history. The example in this section drafts replies to customer reviews in a shop app, so the owner edits a suggestion instead of starting from an empty field. createChat(...) sets the tone once, and generateText(...) returns a complete draft:

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

const draftReply = async (chatId: string, review: string) => {
const { text } = await Llm.generateText({
chatId,
prompt: Draft a reply to this review:\n\n${review},
});
return text;
};
`

The Android API has no native multi-turn sessions, so the plugin keeps the chat history in memory and includes it in every prompt. That history counts toward the input limit of about 4,000 tokens. Create one chat per review, and delete it with deleteChat(...) once the reply is sent.

The other two Android limits apply per chat or per request: temperature must be between 0.0 and 1.0, and maxOutputTokens can be at most 4096. A low temperature such as 0.3 gives more predictable drafts. Only one generation runs per chat at a time, and a second call rejects with GENERATION_IN_PROGRESS, so disable the button while a draft is being written.

A full draft takes several seconds to generate. Google's May 2025 benchmark measured a decode speed of 11 tokens per second on a Pixel 9 Pro, so a reply of a few sentences takes several seconds. streamText(...) shows the draft while Gemini Nano writes it. The plugin emits a textChunk event per piece, tagged with its chatId, and cancelGeneration(...) backs a discard button:

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

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

A canceled generation rejects with GENERATION_CANCELED, which the example turns into null. On Android, cancellation is best-effort, and a few more chunks may arrive after the user taps discard, so have the UI ignore updates for a draft it has already thrown away.

Quota and foreground rules

AICore decides how often and when your app may run Gemini Nano, and two rules from Google's ML Kit GenAI overview apply to every Capacitor app that uses it. The first one is a quota:

> AICore enforces an inference quota per app. Making too many GenAI API requests in a short period will result in an ErrorCode.BUSY response. When receiving such an error, consider using exponential backoff to retry the request. Also, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED can be returned if an app exceeds a long-duration quota (e.g. daily quota).

The second one limits inference to the foreground, as the background usage section of the same page states:

> GenAI API inference is permitted only when the app is the top foreground application. Using the API when the app is not in the foreground, including using a foreground service, will result in an ErrorCode.BACKGROUND_USE_BLOCKED response.

A Capacitor app runs its web code inside the app's own activity, so a generation that starts while the user looks at the screen meets the second rule. A retry timer, a queued request or a push handler that fires after the user switched apps does not.

The Capacitor LLM plugin does not pass ML Kit's error code or its retry delay for quota errors to JavaScript. A quota or background rejection arrives as GENERATION_FAILED with the platform's message, the same code the plugin uses for an exceeded context window and for content blocked by safety guardrails. Matching on the message text is fragile, so treat GENERATION_FAILED as retryable with exponential backoff, cap the attempts, and stop retrying once the app is in the background. The helper below uses the official App plugin to check the app state:

`typescript
import { App } from '@capacitor/app';
import { Llm } from '@capawesome-team/capacitor-llm';

const MAX_ATTEMPTS = 4;

const delay = (milliseconds: number) => new Promise(resolve => setTimeout(resolve, milliseconds));

The helper waits two, four and eight seconds between attempts and gives up after the fourth. Neither a daily quota nor a chat whose history outgrew the input limit recovers within that window, so show a "Try again" button when the helper throws and create a new chat for the next attempt. If your screen queues several drafts, pause the queue when the appStateChange event reports isActive: false. For streams, Google's error reference recommends removing an interrupted result from the UI, so clear the partial draft when streamText(...) rejects.

Testing on devices

Testing Gemini Nano in a Capacitor app requires a phone from the Prompt API list, ideally one per Nano version you target. Frequent test runs in a short period can trigger the BUSY quota error from the previous section. Google's AICore Developer Preview program, which you join through the aicore-experimental Google group and the AICore testing program on Google Play, adds a "Bypass quota limits" toggle to the AICore settings. The toggle exists only on Pixel phones and applies to every app on the device that uses AICore, so switch it off again before you test how your backoff behaves.

The other thing to test is the SDK version. The plugin pulls in Google's com.google.mlkit:genai-prompt dependency with a default of 1.0.0-beta2, while Google's latest release is 1.0.0-beta4 from July 21, 2026. Google's release notes list compatibility fixes for Gemini Nano v4 in that release, so if the Pixel 11 or the Galaxy Z Flip8 and Z Fold8 are in your target group, test generation and streaming on one of them before you ship. The $mlkitGenaiPromptVersion variable in android/variables.gradle overrides the version. Treat that change like any other dependency upgrade and run your tests against it.

ML Kit GenAI plugins

The Capacitor ML Kit project maintains six free, open-source GenAI plugins that call Google's ML Kit GenAI APIs directly on Android, one per API:

Capacitor ML Kit GenAI Summarization plugin for summaries of one to three bullet points
Capacitor ML Kit GenAI Proofreading plugin for grammar and spelling fixes
Capacitor ML Kit GenAI Rewriting plugin for six predefined styles such as Shorten, Friendly and Professional
Capacitor ML Kit GenAI Image Description plugin for short image descriptions in English
Capacitor ML Kit GenAI Prompt plugin for single free-form prompts
Capacitor ML Kit GenAI Speech Recognition plugin for transcription, still in alpha

Like the rest of Capacitor ML Kit, these plugins are unofficial and not affiliated with Google. Their lifecycle mirrors the one above under different names. checkFeatureStatus(...) returns AVAILABLE, DOWNLOADABLE, DOWNLOADING or UNAVAILABLE, but unlike getAvailability() it rejects on iOS and the web, so check the platform first. downloadFeature(...) fetches the feature, and its downloadProgress event carries only totalBytesDownloaded. Without the total size, no percentage is possible, so show an indeterminate bar with a byte counter. For the four feature-specific APIs the explicit download is optional, since Google states that the first inference request triggers it as well. Calling it first is what gives you progress events. These APIs also have their own device list, which includes phones that are missing from the Prompt list.

Google's rule of thumb is to "use Prompt API when you need more customization and flexibility, and use the feature-specific APIs for standard tasks that don't require complex logic." The Capacitor LLM plugin adds chats, textChunk streaming, cancellation and iOS support on top of the Prompt API. Capacitor ML Kit 8.2.0 shows the check, download and summarize flow of the free plugins with code.

FAQ

Do I need to download Gemini Nano before using it?

Yes, the model has to be on the device, but it may already be there. AICore stores one shared copy for all apps, so if another app downloaded it, getAvailability() reports available. Otherwise the status is downloadable, and downloadModel() fetches the model while the downloadProgress event reports a value between 0 and 1.

Does Gemini Nano work offline?

Yes, once the model is on the device. Google states that input, inference and output data are processed locally and that functionality "remains the same without reliable internet connection". The model download and AICore's configuration after a device setup need a connection.

Which devices support Gemini Nano in a Capacitor app?

Gemini Nano runs on the devices from Google's Prompt API device list, such as the Pixel 9, Pixel 10 Pro, Pixel 11, Galaxy S26 Ultra, OnePlus 15 and Xiaomi 15. Each one needs Android API level 26 or higher and a locked bootloader. Check getAvailability() at runtime instead of maintaining your own list.

Why does a generation reject with `GENERATION_FAILED`?

The Capacitor LLM plugin uses GENERATION_FAILED for an exceeded context window, for content blocked by safety guardrails, and for AICore's quota and foreground rules. The error message carries the platform's reason. Retry with exponential backoff while the app is in the foreground, and create a new chat if the retries keep failing.

Can I run Gemini Nano in the background?

No. Google permits GenAI inference only while the app is the top foreground application, and a foreground service does not change that. Start generations from user actions on screen, and move work that arrives in the background, such as a push notification, to the next time the user opens the app.

Is the Capacitor LLM plugin free?

No. It is part of the Capawesome Insiders subscription, which covers every Insiders plugin. Gemini Nano itself costs nothing per request, and the six Capacitor ML Kit GenAI plugins are free and open source.

Stay in the loop

Google changed the ML Kit GenAI APIs several times in 2026, from the Prompt API beta in January to the Gemini Nano v4 fixes in July. Plugin releases that follow those changes, and guides like this one, go out in the Capawesome newsletter first.

Subscribe to the Capawesome Newsletter

Conclusion

Pick the plugin by the shape of your feature. If a summary, a proofread or a rewrite on Android covers it, start with the free ML Kit GenAI plugin for that task. If you need free-form prompts, multi-turn chats or the same code on iOS, build on the Capacitor LLM plugin, and show the feature on every Android device where getAvailability() does not report unavailable, with a fallback everywhere else. The chat and streaming code from the review example runs unchanged on iPhones with Apple Intelligence, as How to Use Apple Intelligence in a Capacitor App shows.

If you have any questions, join us on the Capawesome Discord server. To stay updated on the latest news, subscribe to the Capawesome newsletter.

Publish a Capacitor App on Huawei AppGallery

Robin — Mon, 28 Sep 2026 15:33:35 +0000

Originally published on the Capawesome blog.

Yes, you can publish a Capacitor app on Huawei AppGallery with the same APK or App Bundle you build for Google Play, and Capacitor itself has no Google Play services dependency. The work is in your plugins. Huawei phones launched since late 2019 ship without Google services, so push notifications through Firebase Cloud Messaging, Google Maps and Google Play Billing need a check or a fallback before the first upload. This guide covers the plugin audit, the one-time setup in AppGallery Connect and automatic submission from Capawesome Cloud. Huawei puts AppGallery at more than 580 million monthly active users in more than 170 countries and regions, according to its September 2025 figures.

Key takeaways:

AppGallery accepts the APK or App Bundle you already build for Google Play, so a Capacitor app needs no separate build for Huawei.
Capacitor core depends only on AndroidX and the Cordova framework library, so Google Play services problems on Huawei phones come from individual plugins.
Without Google Play services, FCM, Google Maps, Google Sign-In, Play Billing and unbundled ML Kit modules fail, while Firestore, Crashlytics, Firebase email sign-in and bundled ML Kit models keep working.
The Capacitor Google Play Services plugin's getStatus() method resolves to SERVICE_MISSING on Huawei devices, so the app can hide features that need Google Play services.
A Capawesome Cloud destination uploads builds to AppGallery Connect and, with the release status Completed, submits them for review, which usually takes 1 to 3 working days.

Same build, different store

AppGallery Connect accepts Android apps as APK or App Bundle (AAB), according to Huawei's release overview, so publishing a Capacitor app on Huawei AppGallery starts from the package you already build for Google Play. The Capacitor Android library declares only AndroidX libraries and the Cordova framework as dependencies in its build file, and Capacitor's Android requirements ask for API level 24 and a WebView with Chrome 60 or later, not for Google Play services. The app template applies the google-services Gradle plugin when it finds a google-services.json file, and Firebase states that this build-time plugin is "not related to Google Play services".

If you build with Capawesome Cloud, you have both formats after every build, because it builds an AAB alongside the APK for each Android application module.

The two formats follow different rules on AppGallery. Huawei's APK release guide requires an APK smaller than 4 GB, a 64-bit package for phones and a single APK per version, and Huawei's App Signing service is optional for APKs. An AAB works only after you sign the App Signing agreement and configure a key, because AppGallery Connect compiles the bundle into APKs and re-signs them in 2 to 5 minutes, and it sends back any bundle whose download size exceeds 150 MB (AAB release guide).

We recommend the APK, signed with your own keystore through the Android signing certificate you upload to Capawesome Cloud. The key stays with you, there is no agreement to sign, and the 150 MB limit doesn't apply. Pick that key with care, since Huawei's release FAQ requires every update to keep the package name and the signature of the version already on AppGallery. The destination guide shows where you choose the format, under Publishing format.

Which phones can install that APK depends on the operating system. Huawei phones sold outside China, such as the Pura 80 and the Mate 80 Pro, run Android-based EMUI and install your APK from AppGallery, while HarmonyOS 5 and 6 phones in China run only native HarmonyOS apps, according to Huawei's data migration guide and reporting by SCMP.

Google Play services audit

Google Play services is the dependency to check before your first AppGallery submission, because Huawei phones have shipped without it since the Mate 30 series. CNBC reported at the September 2019 launch that the phones came without the Play Store and Google's apps, four months after the US Commerce Department added Huawei to its Entity List. Google's setup guide states that devices without the Google Play Store don't have Google Play services and tells apps to check for it before they call Google APIs.

A Google feature that fails on a Huawei phone is also a review risk. Huawei's guideline 3.1 expects an app to work properly on mainstream Huawei devices, and its common rejection reasons include crashes and launches with a blank screen.

The table maps common Capacitor plugins to their Google dependency, based on each plugin's Android build file and documentation:

Plugin	Google services dependency	On Huawei devices
`@capacitor/push-notifications`	Firebase Cloud Messaging	Breaks
Capacitor Firebase Cloud Messaging plugin	Firebase Cloud Messaging	Breaks
`@capacitor/google-maps`	Maps SDK for Android	Breaks
Capacitor Google Sign-In plugin	`play-services-auth`	Breaks
Capacitor Purchases plugin (Insiders)	Google Play Billing	Breaks
Capacitor App Update plugin	Play in-app updates	Breaks
Capacitor App Review plugin	Play in-app review	Breaks
Capacitor App Integrity plugin	Play Integrity	Breaks
Capacitor Document Scanner plugin (Insiders)	Play services ML Kit module	Breaks
Capacitor Watch plugin (Insiders)	`play-services-wearable`	Breaks, all methods reject
Capacitor ML Kit Barcode Scanning plugin	Bundled model, Google code scanner	`startScan(...)` works, `scan(...)` breaks
Capacitor Barcode Scanner plugin (Insiders)	Bundled ML Kit model	Works
`@capacitor/geolocation`	`play-services-location`	Works, falls back to `LocationManager`
Capacitor Background Geolocation plugin (Insiders)	`play-services-location`	Works, falls back to the platform location manager
Capacitor MapLibre plugin	None	Not affected
Capacitor Live Update plugin	None	Not affected

Plugins marked Insiders are part of the paid Capawesome Insiders subscription.

The barcode rows split on where the ML Kit model lives. Google documents that an unbundled model is downloaded through Google Play services, while a bundled model is linked into the app at build time and adds about 2.4 MB. In the Capacitor ML Kit Barcode Scanning plugin, scan(...) hands the whole scan to the Google code scanner inside Google Play services, and startScan(...) uses the bundled model.

@capacitor/geolocation keeps working because its enableLocationFallback option defaults to true and switches to Android's LocationManager when the Google Play services location checks fail. Its README warns that LocationManager "may not be as effective" as the Google Play services implementation. The Capacitor Geofences plugin (Insiders) uses Google Play services' GeofencingClient and documents no fallback. In-app updates through the Capacitor App Update plugin need the Play Store, and its openAppStore(...) method opens the app's Play Store entry, the wrong store for an AppGallery install.

Firebase publishes its own per-SDK list. Cloud Messaging has no functionality without Google Play services, and neither does the App Check Play Integrity provider, which the Capacitor Firebase App Check plugin uses on Android. Analytics still sends events, but automatic insights such as demographics need Google Play services. Authentication, Cloud Firestore, Crashlytics, Remote Config, Cloud Storage and Realtime Database don't need it. The exception inside Authentication is the Google provider of the Capacitor Firebase Authentication plugin, which adds play-services-auth when you enable it, so email and password sign-in keeps working while Google sign-in doesn't.

Degrade gracefully

The Capacitor Google Play Services plugin tells your app at runtime whether Google Play services exists on the device, so you can hide the features from the table before a Huawei user or reviewer opens them. The plugin is free, depends only on play-services-base, and its documentation states that the check works on any Android device, including devices without Google Play services. To install it, refer to the Installation section of the plugin documentation.

getStatus() resolves to SERVICE_MISSING when Google Play services is not installed at all, which the plugin documentation names as the case for Huawei devices with Huawei Mobile Services. The following example skips push registration and turns off the map screen on those devices:

import { Capacitor } from '@capacitor/core';
import { PushNotifications } from '@capacitor/push-notifications';
import { GooglePlayServices, Status } from '@capawesome/capacitor-google-play-services';

export const features = { maps: true, pushNotifications: true };

const isGooglePlayServicesMissing = async () =&gt; {
  if (Capacitor.getPlatform() !== 'android') {
    return false;
  }
  const { status } = await GooglePlayServices.getStatus();
  return status === Status.ServiceMissing;
};

const initializeFeatures = async () =&gt; {
  const missing = await isGooglePlayServicesMissing();
  features.maps = !missing;
  features.pushNotifications = !missing;
  if (features.pushNotifications) {
    await PushNotifications.register();
  }
};

The platform check keeps iOS and web builds away from the plugin, which is Android-only and rejects every call on other platforms. Statuses such as SERVICE_DISABLED and SERVICE_VERSION_UPDATE_REQUIRED mean Google Play services is installed but disabled or outdated, which makeAvailable() can fix with the system dialog. On a Huawei phone, makeAvailable() is rejected, because there is no Play Store to install Google Play services from.

Hiding a feature is the minimum. When Huawei users need the feature itself, HMS Core has replacements. For push, that is Push Kit, and since there is no official Capacitor HMS plugin, Huawei's documented Capacitor route is its Cordova plugin @hmscore/cordova-plugin-hms-push, while devices with Google Play services keep the FCM setup from Capacitor Push Notifications: The Complete Guide. Map Kit, Account Kit and HUAWEI IAP cover maps, sign-in with a HUAWEI ID and in-app purchases, and AppGallery guideline 6.4 recommends Huawei IAP for apps with in-app purchases without requiring it. Huawei's HMS Toolkit is no shortcut here. Its Convertor rewrites Java and Kotlin projects, not a web layer, and Huawei is sunsetting the toolkit, with overseas services ending on December 30, 2026.

AppGallery Connect setup

AppGallery Connect requires a verified HUAWEI Developers account before you can create an app, and the account is free to register for individual and enterprise developers. Individuals verify with a bank document plus an ID card, passport or driver's license, and the bank document has to show the full name in English and stay valid for at least 6 months (individual verification). Enterprises submit a business license or a DUNS number renewed within the last two years. Huawei reviews either within 1 to 2 working days and emails the result. Two choices are permanent. An individual account can't become an enterprise account later, and the country or region you select during verification can't be changed.

With the account verified, create the Android app under Apps and atomic services on the Android tab, with APK as the package type. The device type "Mobile phone" includes tablets. The package name and the App or Game category are fixed once set, and the app name has to match the one in your package.

The first version needs a store listing, which Huawei specifies in its APK release guide and its asset requirements:

Icon: 216 × 216 or 512 × 512 pixels, PNG up to 2 MB, not animated.
Screenshots: 3 to 8 images at 800 × 450 or 450 × 800 pixels.
Introductions: A brief introduction of up to 80 characters, with 25 or fewer advised, and a full introduction of up to 8,000 characters.
Age rating: A questionnaire that produces the rating.
Privacy policy: A URL if the app collects user data, plus an easy-to-find link inside the app under guideline 7.1.
Language: English (US) in the app package and on the App information page, if you distribute outside the Chinese mainland.
Test account: Sign-in details for Huawei's reviewers if the app requires sign-in.

Guideline 1.16 bans names, icons and imagery of other device brands and app platforms from your listing, so screenshots with a Google Play badge have to go. If the same app is already on Google Play, AppGallery can reject it as a duplicate. Huawei's release FAQ asks the owner to email Huawei operations from the contact details used on Google Play, with the developer name and email address of both accounts. For assets you share with Apple and Google, see How to Prepare Your App Store Listing.

The last one-time step is the API client that Capawesome Cloud uses to reach AppGallery Connect, which the destination guide covers under Obtaining credentials.

Submit with Capawesome Cloud

A Huawei AppGallery destination lets Capawesome Cloud upload a finished Android build to AppGallery Connect, so nobody has to upload APKs in the browser. You create it once, in the Console with the fields listed under Configuration or with apps:destinations:create from the Capawesome CLI:

npx @capawesome/cli apps:destinations:create \
  --app-id 00000000-0000-0000-0000-000000000000 \
  --name "AppGallery Production" \
  --platform android \
  --type huawei-appgallery \
  --huawei-app-id  \
  --huawei-client-id  \
  --huawei-client-secret  \
  --android-build-artifact-type apk \
  --android-release-status completed

--app-id is the ID of your app in Capawesome Cloud, while the three --huawei-* values come from AppGallery Connect as described under Obtaining credentials. The artifact type follows the APK recommendation above, and the release status is explained below. Huawei's Publishing API can neither create an app nor complete its content rating, which is why the listing from the previous section stays a one-time manual step.

From then on, a submission is one command. apps:deployments:create takes the build number and the destination name:

npx @capawesome/cli apps:deployments:create --build-number 42 --destination "AppGallery Production"

In the Console, the Deployments page does the same with Create deployment. The destination's release status decides whether the upload stays a draft for you to submit in AppGallery Connect or goes to review automatically, as the guide explains under Release status. The same build number can go to a Google Play Store destination in a second deployment, so one native build serves both stores.

To take the command out of your release process, attach the destination and your signing certificate to an automation that triggers on v* tags. Every matching tag then runs the pipeline from Git to build to AppGallery Connect, as described in Submit Automatically After a Build and the auto-submit walkthrough.

A successful deployment means Huawei has the build, not that users can install it (After submitting). Huawei's APK release guide says app review usually takes 1 to 3 working days and that rejections arrive by email. Reviewers also check each release country or region against local policies and remove the ones where the app doesn't comply. If a deployment fails because another version is still under review, the guide covers the fix under Submission fails because a version is under review.

FAQ

Can I publish my Capacitor app on Huawei AppGallery?

Yes. AppGallery Connect accepts the same APK or AAB you build for Google Play, and Capacitor core has no Google Play services dependency. Check your plugins first, because Huawei phones ship without Google Play services, and features such as FCM push notifications, Google Maps and Google Play Billing don't work there. A Capawesome Cloud destination can then upload and submit every release.

Do Huawei phones still run Android apps?

Huawei phones sold outside China do. Huawei's international models run Android-based EMUI, currently EMUI 15 and 16, and install APKs from AppGallery. Phones in China that run HarmonyOS 5 or 6 accept only native HarmonyOS apps, so a Capacitor APK doesn't reach them.

Does Capacitor need Google Play services?

No. The Capacitor Android library depends only on AndroidX and the Cordova framework. Google Play services comes in through plugins such as @capacitor/push-notifications, which uses Firebase Cloud Messaging, and @capacitor/google-maps, which uses the Maps SDK for Android. That is why the audit happens at the plugin level.

How long does AppGallery review take?

Huawei's current release documentation says app review usually takes 1 to 3 working days, and a rejection arrives by email. If your developer account is new, add 1 to 2 working days for identity verification before your first submission.

Can I upload the same APK to Google Play and AppGallery?

Yes. AppGallery takes the APK you build for Google Play as it is. If Google Play signs your app through Play App Signing, installs from Google Play carry the app signing key that Google holds, while installs from AppGallery carry the key you signed the APK with, so the two usually report different certificate fingerprints.

Does Capawesome Cloud submit to AppGallery automatically?

Yes. A Huawei AppGallery destination uploads the build to AppGallery Connect and, with the release status Completed, submits the version for review. Attach the destination to an automation that triggers on v* tags, and every release tag goes from Git to AppGallery without a manual step.

Try it yourself

Once your Android builds run in Capawesome Cloud, AppGallery is one destination away. Upload your keystore, add a Huawei AppGallery destination and push a v* tag to watch the first version arrive in AppGallery Connect. You can run all of it during the 14-day free trial.

Try Capawesome Cloud Free

Final thoughts

Run the audit before the first upload. If none of your plugins lands in a "Breaks" row, submit the APK you already build. If one does, gate it with getStatus(), ship without that feature on Huawei phones, and add an HMS replacement only when Huawei users can't do without it. Sign the APK with your own keystore unless you want Huawei to hold the key, and hand the submissions to a tag automation once the first listing is live.

Before that first submission, put the APK on a Huawei phone without a store, as described in How to Distribute iOS and Android Apps to Testers. Questions about a specific plugin on Huawei devices are welcome on the Capawesome Discord server, and the Capawesome newsletter announces new plugins and Cloud features as they ship.

Build and Deploy iOS Apps with Gitea Actions

Robin — Sun, 27 Sep 2026 14:00:22 +0000

An iOS build needs Xcode, Xcode needs macOS, and Gitea Actions doesn't come with a Mac. Your Node, Go, or Android jobs run fine on Linux runners, but the iOS build has nowhere to go. In this guide, we'll set up Gitea Actions iOS builds that start on the Linux runner you already have and hand the macOS work to Capawesome Cloud, which compiles and signs the app and uploads it to TestFlight. We'll also cover the self-hosted Mac alternative, a Gitea server behind a firewall, and a setup that needs no workflow file at all.

Key takeaways:

gitea.com registers runners only for its gitea organization, and Gitea Cloud names no OS for its on-demand runners, so iOS builds need your own Mac or a build service.
Gitea Runner can run jobs directly on a Mac through a host label, but those jobs run without isolation, and Xcode, signing, and uploads stay your responsibility.
A Gitea Actions job on ubuntu-latest can run apps:builds:create, which builds, signs, and submits the app to TestFlight on Capawesome Cloud's Apple Silicon M4 machines.
If Capawesome Cloud can't reach your Gitea server, the runner checks out the code and uploads it with --path, so no inbound firewall rule is needed.
Capawesome Cloud Automations build on Gitea tag pushes through a webhook, with no workflow file and no runner.

macOS runners on Gitea

Gitea Actions only runs jobs on runners that someone has registered with the instance, so the runners available to you depend on where your Gitea lives. On gitea.com, the Gitea Actions FAQ states that runners are registered only for the gitea organization's repositories, so every other user brings their own. Gitea Cloud, the managed offering from CommitGo, starts runners on demand, but neither its product page nor its pricing page names an operating system, and the Enterprise plan lists Kubernetes autoscaling runners. A self-hosted Gitea instance has exactly the runners your team registers.

An iOS build can't avoid macOS for its final steps. Xcode, xcodebuild, and codesign only run on Apple hardware, whether the project is native Swift, Capacitor, or Cordova. That leaves two options. You can register a Mac as a runner, or keep the job on Linux and send the build to a service that runs Macs.

Self-hosting a Mac runner

Gitea Runner (formerly act_runner) ships official macOS binaries, so a Mac mini can pick up Gitea Actions jobs like any other runner. To run jobs directly on the Mac instead of in a container, register the runner with a host label:

gitea-runner register --no-interactive \
  --instance https://gitea.example.com \
  --token  \
  --name mac-mini-1 \
  --labels macos:host

A workflow then targets the Mac with runs-on: macos, and every step uses the Xcode installed on that machine:

jobs:
  build-ios:
    runs-on: macos
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -project MyApp.xcodeproj -scheme MyApp -archivePath build/MyApp.xcarchive archive

The Gitea Runner documentation lists the trade-offs of host mode. Jobs on a host label run without isolation from each other, a docker:// action or a service container still needs a Docker daemon on the Mac, and the labels guide recommends distinct label names so a workflow written for ubuntu-latest never runs unsandboxed on your machine. The binary installation guide includes a launchd plist that keeps the runner alive across reboots.

The archive step above is the easy part. Everything after it is yours to build and maintain:

Xcode upgrades. When Apple raises the minimum SDK for App Store submissions, every Mac runner needs the new Xcode installed and tested.
Signing. The distribution certificate lives in a keychain that has to be unlocked for non-interactive jobs, and provisioning profiles have to be installed and renewed on each machine.
Export and upload. xcodebuild -exportArchive needs an ExportOptions.plist, and the TestFlight upload needs App Store Connect credentials and a tool such as fastlane.
The machine itself. macOS updates, disk space filled by DerivedData and old archives, and builds queueing behind each other on a single Mac.

If your team already runs Macs and someone owns them, this setup works. Otherwise, the rest of this guide keeps the job on Linux.

Offloading to Capawesome Cloud

Capawesome Cloud runs iOS builds on Apple Silicon M4 machines and exposes them through the Capawesome CLI, so a Gitea Actions job only needs Node.js to start one. The job runs apps:builds:create on your existing ubuntu-latest runner. Capawesome Cloud then clones the commit from your Gitea server through a Git connection, runs the web build and native sync for Capacitor and Cordova apps, compiles with Xcode, signs the app with a certificate you uploaded once, and can submit the result to TestFlight.

The default Gitea Runner image (docker.gitea.com/runner-images:ubuntu-latest) already includes Node.js, so the job needs no actions/setup-node step. Because Capawesome Cloud clones the repository itself, it needs no actions/checkout either. Each build starts in a fresh macOS environment, and Xcode versions come from the selected build stack, so moving to a new Xcode means changing one flag instead of reinstalling a Mac.

One-time setup

The Capawesome Cloud side of the setup takes four steps. The Gitea connection belongs to your Capawesome Cloud organization and is reused by every app, and everything else is set up once per app. Create the app first, either in the Console or with npx @capawesome/cli apps:create.

Connect Gitea. Create a Gitea access token under Settings → Applications with the read:user, read:organization, and read:repository scopes (or write:repository if you plan to use Automations, covered below). Add a Gitea connection in Capawesome Cloud with that token. For a self-hosted server, enable Self-hosted or enterprise instance and enter its URL; on gitea.com, leave the option off. Then open the app's Git repository page and connect the repository. The Gitea integration guide walks through each field.
Upload signing assets. Upload your distribution certificate (.p12) and its provisioning profile under a name such as Production iOS. The iOS certificates guide has the details, and the free iOS Certificate Generator creates the CSR and .p12 in your browser if there's no Mac at hand.
Add a destination. Create an Apple App Store destination named TestFlight with an App Store Connect API key, so Capawesome Cloud can upload builds for you.
Store the token. Create an API token and add it to your Gitea repository under Settings → Actions → Secrets as CAPAWESOME_TOKEN, which the CLI reads automatically. Add the app ID under Settings → Actions → Variables as CAPAWESOME_APP_ID. Gitea rejects secret and variable names that start with GITEA_ or GITHUB_, so keep the CAPAWESOME_ prefix.

The release workflow

The release workflow builds and ships the iOS app whenever someone pushes a version tag. Save it as .gitea/workflows/ios-release.yaml:

name: iOS release

on:
  push:
    tags:
      - "v*"

jobs:
  release-ios:
    runs-on: ubuntu-latest
    env:
      CAPAWESOME_TOKEN: ${{ secrets.CAPAWESOME_TOKEN }}
    steps:
      - run: |
          npx @capawesome/cli@4.22.0 apps:builds:create \
            --app-id "${{ vars.CAPAWESOME_APP_ID }}" \
            --platform ios \
            --type app-store \
            --certificate "Production iOS" \
            --destination "TestFlight" \
            --git-ref "${{ gitea.sha }}" \
            --yes

The apps:builds:create command builds the exact commit behind the tag. ${{ gitea.sha }} is Gitea's context for that commit, and ${{ github.sha }} works as an alias if you're porting a GitHub workflow. --type app-store produces an IPA for TestFlight and the App Store; the other iOS build types are simulator, development, ad-hoc, and enterprise. --destination submits the signed build once it succeeds.

The command waits for the build and exits non-zero if it fails, so a failed build marks the Gitea Actions run as failed. Gitea sets CI=true in every run, which keeps the CLI from prompting for input, and the CLI scripting guide explains the rest of its non-interactive behavior. Pinning the CLI version keeps runs reproducible. To inject build-time variables and secrets, add --environment with an environment, and to pick a specific Xcode, set --stack.

A release now starts with a version tag pushed to Gitea:

git tag v1.4.0
git push origin v1.4.0

Anyone who can push a v* tag can now ship to TestFlight. A protected tag rule for v* under Settings → Tags limits that to the users and teams you choose.

Manual release approval

Gitea Actions has no deployment approvals. The comparison with GitHub Actions notes that jobs..environment is ignored, so a required-reviewer environment won't pause a job. A pattern that works instead is to split building from shipping. Build on every push to main without a destination, then promote a chosen build with a manually dispatched workflow.

For the build half, reuse the release workflow with a branch trigger and drop the --destination line:

on:
  push:
    branches:
      - main

The promote workflow takes a build number as input and calls apps:deployments:create. Save it as .gitea/workflows/ios-promote.yaml:

name: iOS promote

on:
  workflow_dispatch:
    inputs:
      build_number:
        description: Build number to submit to TestFlight
        required: true

jobs:
  promote-ios:
    runs-on: ubuntu-latest
    env:
      CAPAWESOME_TOKEN: ${{ secrets.CAPAWESOME_TOKEN }}
    steps:
      - run: |
          npx @capawesome/cli@4.22.0 apps:deployments:create \
            --app-id "${{ vars.CAPAWESOME_APP_ID }}" \
            --build-number "${{ inputs.build_number }}" \
            --destination "TestFlight"

Dispatching with inputs requires Gitea 1.23 or later, which added manual runs with an input form in the Actions UI. Take the build number from the build list in the Capawesome Cloud Console. Gitea has no reviewer list to check against, so the gate is whoever starts the run.

Builds for QA don't have to go through TestFlight at all. An ad-hoc build with --share gets a public install link for testers, as described in Share a build.

Servers behind a firewall

Capawesome Cloud has to reach your Gitea server to clone a repository by --git-ref. When the server is only reachable from inside your network, the Gitea Actions runner is usually the one machine that already has access. Let it check out the code and upload the source with --path instead:

steps:
  - uses: actions/checkout@v4
  - run: |
      npx @capawesome/cli@4.22.0 apps:builds:create \
        --app-id "${{ vars.CAPAWESOME_APP_ID }}" \
        --platform ios \
        --type app-store \
        --certificate "Production iOS" \
        --destination "TestFlight" \
        --path . \
        --yes

The job keeps the same env block as the release workflow. The CLI packs the directory into an archive, respecting your .gitignore, and uploads it, so no inbound connection to your network is needed. The build without Git guide lists what you give up. These builds show no commit metadata in the Console, can't be started or re-run from the Console, and don't work with Automations. By default, actions/checkout itself is downloaded from github.com, so the runner needs outbound access there.

To keep the Git connection instead, the firewall guide compares a reverse tunnel (the recommended option), repository mirroring, and IP allowlisting.

Builds without a workflow

Capawesome Cloud Automations start builds from Gitea pushes without any Gitea Actions workflow. An automation receives your repository's push events through a webhook and builds when a matching branch or tag arrives, so a tag automation can replace the release workflow entirely:

Give the Gitea access token the write:repository scope, so Capawesome Cloud can register the webhook.
On the app's Automations page, create an automation with the trigger type Tag and the pattern v*. A second pattern, !v*-*, skips pre-release tags such as v1.4.0-rc.1 (trigger on tags).
Choose iOS as the platform and attach the Production iOS certificate and the TestFlight destination in the build settings.

Capawesome Cloud registers the webhook for you. On a self-hosted instance that registration can fail, for example because of missing permissions, and the webhook guide then lists the URL and secret to add in Gitea's repository settings by hand. Automations clone through the Git connection, so they need a Gitea server that Capawesome Cloud can reach. They also work on an instance with no registered runners, and a commit with [skip ci] in its message skips them.

The trade-off is control. An automation builds every matching tag, while a workflow can run your tests first and start the build only when they pass.

FAQ

Does Gitea Actions have macOS runners?

Gitea Actions doesn't come with a Mac. gitea.com registers runners only for the gitea organization's repositories, and Gitea Cloud describes on-demand runners without naming an operating system. You can register your own Mac with Gitea Runner using a host label, or run the job on Linux and hand the iOS build to a service such as Capawesome Cloud.

Can Gitea Runner build iOS apps on my own Mac?

Yes. Register Gitea Runner on the Mac with a label such as macos:host and target it with runs-on: macos. The steps then run directly on the machine with its installed Xcode and without isolation between jobs, and you maintain Xcode, the signing keychain, and the App Store Connect upload yourself.

Do I need Gitea Actions at all?

No. Capawesome Cloud Automations trigger iOS builds on Gitea branch or tag pushes through a webhook and can submit the result to TestFlight, with no workflow file and no runner. Use Gitea Actions when tests or other jobs should run before the build.

Does this work with a Gitea server behind a firewall?

Yes. A runner inside your network can run actions/checkout and upload the source with apps:builds:create --path ., so Capawesome Cloud never connects to your server. To keep the Git connection and Automations instead, expose the server through a reverse tunnel, a mirror, or an IP allowlist.

Which workflow directory does Gitea read?

Gitea looks for .gitea/workflows first and falls back to .github/workflows, using the first directory that exists. Once a repository has a .gitea/workflows directory, Gitea ignores the workflows in .github/workflows.

Does this work for Capacitor and Cordova apps?

Yes. Capawesome Cloud builds native Swift and Objective-C projects as well as Capacitor and Cordova apps, and it runs the web build and native sync for the hybrid ones. The Gitea workflow is the same for all of them.

Try it yourself

If iOS is the one job your Gitea runners can't handle, connect your Gitea server, upload a certificate, and push a tag. Capawesome Cloud comes with a 14-day free trial, which covers your first builds.

Try Capawesome Cloud Free

Final thoughts

Start with a tag automation if pushing a tag is your whole release process. Move to the Gitea Actions workflow once tests have to pass before a build starts, and switch to --path when Capawesome Cloud can't reach your server. Register a Mac as a runner only if someone on your team already maintains Macs.

For the same flow without a CI layer, read How to Build and Deploy iOS Apps Without Owning a Mac. If you have questions, join the Capawesome Discord server, and subscribe to the Capawesome newsletter to stay up to date.

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.

DEV Community: Robin

Google Play DEX Code Optimization in Capacitor Apps

Prerequisites

Play's DEX optimization requirement

Enable R8

Rules you need

Why the keep rule

Missing class errors

Verify locally

Conclusion

How to Add Geofencing to an Ionic App

Prerequisites

Platform setup

Request permissions

Register a geofence

Handle transitions

Notify the user

Queue missed transitions

Remove geofences

Conclusion

Reading Step Counts on iOS and Android with Capacitor

Prerequisites

Where steps come from

Check availability

Request step permission

Today's total

Daily and weekly buckets

The double-counting trap

Platform limits

Conclusion

How to Fix AdMob Banner Overlap in a Capacitor App

Prerequisites

Why the banner overlaps

Resize the web view

Pad in overlay mode

Ionic layout specifics

Hide, resume, remove

Community plugin comparison

Conclusion

Downloading Files in the Background in Capacitor

Prerequisites

Why fetch stops

Native transfer engines

Start a download

Listen for results

Platform setup

What survives what

Restore after relaunch

Conclusion

Capacitor Barcode Scanning Without Google Play Services

Devices without Play services

Bundled vs. unbundled model

The ML Kit plugin

Detect Play services first

The Insiders plugin

Which one to pick

FAQ

Does Capacitor barcode scanning work without Google Play services?

Does the ML Kit plugin work on Huawei devices?

How much does the bundled model add to the app size?

Do I still need the DEPENDENCIES meta-data?

Does barcode scanning work offline?

Is the Capacitor Barcode Scanner plugin free?

Related posts

Try Capawesome Cloud

Conclusion

MapLibre vs. Google Maps: Which Map SDK to Use?

Renderer vs. platform

Google Maps pricing

The map ID trap

MapLibre tile costs

Terms and lock-in

Rendering

Offline maps

Data and search

Which to pick

FAQ

How much does Google Maps cost per month in 2026?

Is MapLibre free to use commercially?

Do I need an API key to use MapLibre?

Do I still need the `DEPENDENCIES` meta-data?

Why does a generation reject with `GENERATION_FAILED`?