Platform setup

Android setup

Step 1: Initialize

pnpm tauri android init

The plugin automatically registers its Android bridge and Glance widget receiver from the plugin AAR — you do not write a Glance AppWidget in Kotlin for the default path.

No Kotlin code required — the built-in receiver reads widget config from shared storage and renders it via Jetpack Glance.

Step 2: Match the SharedPreferences group

The Glance receiver resolves the store name in this order (WidgetStoreKeys.resolveGroup):

  1. Per-instance meta widgetId:{appWidgetId} binding (after pin)
  2. Manifest <meta-data android:name="tauri_widget_group" …/> on the Glance receiver
  3. Fallback candidates: app package name, group.<package>, and hyphenated variants

Your JS group argument to setWidgetConfig must be one of those names. A random group.com.example.myapp from the desktop tutorial will not match unless you set the same value in meta-data.

Simplest path — use the package name:

// e.g. identifier / applicationId is com.example.myapp
await setWidgetConfig(config, "com.example.myapp", widgetId);

Optional custom group — add meta-data on the merged application (keep the plugin’s APPWIDGET_UPDATE receiver intact). Prefer only injecting meta-data rather than replacing the whole <receiver>:

<!-- In your app AndroidManifest <application>, after merger with the plugin: -->
<meta-data
    android:name="tauri_widget_group"
    android:value="group.com.example.myapp" />

If you override the Glance <receiver> yourself, keep the plugin class, provider meta-data, and intent-filter, and declare xmlns:tools when using tools:replace:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
  <application>
    <receiver
        android:name="git.s00d.widgets.TauriGlanceWidgetReceiver"
        android:exported="true"
        android:label="My Widget"
        tools:replace="android:label">
      <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
      </intent-filter>
      <meta-data
          android:name="android.appwidget.provider"
          android:resource="@xml/tauri_widget_info" />
      <meta-data
          android:name="tauri_widget_group"
          android:value="group.com.example.myapp" />
    </receiver>
  </application>
</manifest>

Then call setWidgetConfig(..., "group.com.example.myapp", widgetId) with the same string.

Step 3: Run

pnpm tauri android dev

Step 4: Add widget to home screen

Long-press the home screen → Widgets → find your app → drag to screen.

After pinning, call setWidgetConfig for the logical widgetId bound to that instance (see Multi-widget).

What the plugin adds to your manifest

The plugin AAR merges these entries; you do not declare them yourself. Requirements: minSdk 23 (Android 6.0) and compileSdk 35 or newer in your app (Jetpack Glance 1.2).

EntryPurpose
TauriGlanceWidgetReceiver + @xml/tauri_widget_infoThe widget. On Android 15+ the picker shows a preview generated from your stored config (refreshed after setWidgetConfig; the system rate-limits it). The info XML sets a loading layout (tauri_widget_loading, shown until the first draw), a picker preview (tauri_widget_preview layout / drawable), a description (@string/tauri_widget_description) and widgetFeatures="reconfigurable|configuration_optional".
WidgetConfigActivity (APPWIDGET_CONFIGURE)Configuration / reconfigure screen. Lists the choices from setWidgetInstances(widgetId, [...]); the picked id becomes that placement's instance (config:{id}#{instance}, data:…, state:…, {{instance}}). Without choices it closes at once, so adding a widget never stops on an empty screen.
TauriWidgetFileProvider (${applicationId}.tauri_widgets.files)Downloaded widget images are handed to the launcher by content URI, so large photos do not hit the RemoteViews bitmap limit. A <queries> entry for the HOME intent lets the plugin grant the launcher read access.
WorkManager (androidx.work, merged by the library)source fetches run as unique WorkManager jobs per placement (network required, exponential backoff, 3 tries), never inside a draw. The cache keeps the last good response.
WidgetTickReceiver, ActivityActionReceiverScheduled redraws (entries, due source) and live-activity buttons.
POST_NOTIFICATIONS, POST_PROMOTED_NOTIFICATIONSLive activities; Android 16 Live Updates.
com.samsung.android.support.ongoing_activity (application meta-data)Samsung One UI 7 Live Notifications / Now Bar for the activity notification (see Samsung).
com.samsung.android.appwidget.provider → @xml/tauri_widget_samsung on the receiver, widgetCategory="home_screen|keyguard"Galaxy Z Flip cover screen (Flex Window) and lock-screen hosts.

Override any of the strings, the tauri_widget_preview drawable or the layouts by defining a resource with the same name in your app. To drop the configuration screen, override @xml/tauri_widget_info without android:configure.

Local state on the widget

Buttons, toggles and links with set change the placement's state in the widget process (no app launch): the tap writes state:{widgetId}#{appWidgetId} (or the configured instance), redraws that placement, then still queues action for the app. A running app also gets widget-state-changed. See the state / set fields in the element reference.

Live Updates (Android 16)

Live activities ask for promotion (setRequestPromotedOngoing, setShortCriticalText, ProgressStyle on API 36). The user decides in system settings. The Android bridge has canPostPromotedNotifications (is promotion allowed now) and openPromotionSettings (opens that settings page; the app's notification settings before Android 16).

Lock screen and out-of-order updates

  • visibility: "private" posts a redacted public version for the secure lock screen: app name, timer (endsAt / startedAt), progress and tint; no title, body or buttons. "secret" hides the notification there; "public" (default) shows it in full.
  • timestamp (Unix ms): an update older than the last applied one for that id is dropped and the bridge answers applied: false, as on iOS. A new start always applies; endActivity forgets the last timestamp.

Samsung: Now Bar, cover screen

  • Now Bar / Live Notifications. On Samsung phones below Android 16 (One UI 7) the activity notification also carries Samsung's android.ongoingActivityNoti.* extras: title → primary line, body → secondary line, shortCriticalText (else title) → status-bar chip, tint → chip and progress color, progress, actions. Samsung shows them only for media apps and allow-listed packages. On One UI 8+ (Android 16) the Now Bar takes the standard Live Update instead, so no Samsung extras are added there (they would cancel the promotion). The user still enables the app in the Now Bar / Live notifications settings. private shows the app name in the Now Bar; secret adds nothing.
  • Cover screen (Galaxy Z Flip Flex Window). The receiver declares <samsung-appwidget-provider display="sub_screen"> and keyguard. The user adds the widget under Settings > Cover screen > Widgets. On a lock-screen host (cover screen, Android 16 lock-screen hub) the widget draws its small layout. You add nothing to the app manifest. Samsung recommends minWidth 352dp / minHeight 339dp for the cover screen. If your device does not list the widget with the plugin's 110 dp minimum, override @xml/tauri_widget_info with those sizes. To keep the widget off lock screens, override it with widgetCategory="home_screen".

Long lists

A list with items scrolls (Glance LazyColumn, a launcher ListView) once its rows are taller than the widget. Shorter lists draw as before. At most 50 rows are sent; the rest show as "+N more". Lists with custom children do not scroll.

Custom Widget Provider (advanced)

If you need custom behavior, create your own GlanceAppWidget / GlanceAppWidgetReceiver and keep the same shared-group + config:{widgetId} contract.


When it fails

  • Empty tile: JS group ≠ what Glance resolves (log package name / meta-data).
  • Check adb logcat | grep -i widget for errors.
  • Canvas bitmaps larger than 512px are automatically capped.
  • Bitmap data is compressed to stay under the Binder IPC 500KB limit.
  • Prefer flat vstack / hstack; always set progress.label.

More symptoms: Troubleshooting index.