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):
- Per-instance meta
widgetId:{appWidgetId}binding (after pin) - Manifest
<meta-data android:name="tauri_widget_group" …/>on the Glance receiver - 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).
| Entry | Purpose |
|---|---|
TauriGlanceWidgetReceiver + @xml/tauri_widget_info | The 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, ActivityActionReceiver | Scheduled redraws (entries, due source) and live-activity buttons. |
POST_NOTIFICATIONS, POST_PROMOTED_NOTIFICATIONS | Live 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 answersapplied: false, as on iOS. A new start always applies;endActivityforgets 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(elsetitle) → 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.privateshows the app name in the Now Bar;secretadds nothing. - Cover screen (Galaxy Z Flip Flex Window). The receiver declares
<samsung-appwidget-provider display="sub_screen">andkeyguard. 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 itssmalllayout. You add nothing to the app manifest. Samsung recommendsminWidth 352dp/minHeight 339dpfor the cover screen. If your device does not list the widget with the plugin's 110 dp minimum, override@xml/tauri_widget_infowith those sizes. To keep the widget off lock screens, override it withwidgetCategory="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 widgetfor 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 setprogress.label.
More symptoms: Troubleshooting index.