Support per-instance Android widget configuration

[V3RON]

Problem statement

Android assigns every placed app widget a unique appWidgetId. That instance id is the right storage key for user configuration such as label: "London" on one weather widget and label: "New York" on another.

Voltra currently supports Android widget type-level flows well:

• requestPinAndroidWidget(widgetId) can request pinning a configured Voltra widget provider.
• updateAndroidWidget(widgetId, variants) renders and stores one payload for the Voltra widget type id.
• getActiveWidgets() can discover placed widget instances and exposes Android instance ids.
• Dynamic Widgets already receive env.configuration during Hermes rendering.

What is not possible today:

• A user cannot configure each placed Android widget instance independently.
• setWidgetConfiguration(widgetId, key, value) stores values by Voltra widget type id, so all instances of that widget type share the same configuration.
• updateAndroidWidget(widgetId, variants) stores one payload per widget type and fans it out to all placed instances.
• Generated appwidget-provider XML does not attach an Android android:configure Activity, so launcher-added widgets have no guaranteed insert-time configuration hook.
• Pin-with-preview and pin-without-preview only report whether the pin request was accepted. They do not currently surface the created appWidgetId or enter a per-instance configuration flow.
• Server-driven widgets fetch one payload per widget type id, so a server cannot reliably return different content for each placed instance.

Android/Glance provides the lifecycle hook, but not the UI. A widget configuration Activity can receive AppWidgetManager.EXTRA_APPWIDGET_ID, persist app-defined configuration, update the exact Glance widget instance, and return RESULT_OK. Voltra needs to bridge that platform contract to React Native and to its widget storage model.

Suggested solution

Introduce per-instance Android widget configuration as a Voltra runtime feature.

High-level changes:

• Treat widgetTypeId and appWidgetId as distinct concepts in public API and native code.
• Add generated Android configuration Activity support from the Expo plugin.
• Let the generated configuration Activity act as a thin trampoline into React Native rather than providing built-in form UI.
• Store Dynamic Widget configuration by appWidgetId, while keeping appIntent.parameters[].default keyed by widget type.
• Update VoltraClientGlanceWidget to resolve GlanceId -> appWidgetId and pass per-instance configuration into env.configuration.
• Add targeted client-rendered widget update support, for example updateAndroidWidgetInstance(appWidgetId, variants) or updateAndroidWidget(widgetTypeId, variants, { appWidgetId }).
• Extend server-driven widgets to include both widgetId / widgetTypeId and appWidgetId in requests, fetch/render per instance, and cache payloads per instance.
• Add opt-in configuration behavior in widget config, with optional support for reconfigurable and configuration_optional on Android 12+.

Expected outcome:

• Two widgets of the same Voltra type can be placed on the home screen with different user configuration.
• Launcher-added widgets and in-app pinned widgets can enter the same per-instance configuration flow.
• Dynamic Widgets rendered through Hermes receive correct per-instance env.configuration.
• Client-rendered and server-driven update paths can update one instance without overwriting all sibling instances.

[V3RON]

Proposed approach: secondary React Native root for configuration

Use Android's required configuration Activity contract, but keep the actual configuration UI app-owned and written in React Native.

Decisions

• Derive configurability from appIntent.parameters. If a widget declares parameters, emit Android configuration support for it. No separate configurable: true flag.
• If all parameters have defaults, mark the widget as optional to configure on Android 12+ with configuration_optional. If any parameter lacks a default, first-add configuration remains mandatory.
• Update requestPinAndroidWidget so callers can receive information about whether the widget was actually added and whether it entered/completed configuration.
• Keep configuration values string-only for parity with current appIntent.parameters[].default.

Public API sketch

Add a JS registration API:

import { registerAndroidConfigurableWidgetComponent } from '@use-voltra/android-client'

registerAndroidConfigurableWidgetComponent(WidgetConfigurationScreen)

The component receives the Android widget instance and Voltra widget type metadata:

type AndroidConfigurableWidgetProps = {
  widgetTypeId: string
  appWidgetId: number
  initialConfiguration: Record<string, string>
  defaults: Record<string, string>
}

The app completes or cancels through Voltra runtime APIs:

await completeAndroidWidgetConfiguration(appWidgetId, {
  label: 'London',
})

await cancelAndroidWidgetConfiguration(appWidgetId)

completeAndroidWidgetConfiguration should accept Record<string, string> only.

Update pin API result shape so it can communicate request acceptance and final instance/configuration state, for example:

type RequestPinAndroidWidgetResult = {
  accepted: boolean
  added?: boolean
  appWidgetId?: number
  widgetTypeId?: string
  configuration?: 'not_required' | 'started' | 'completed' | 'canceled'
}

Exact async shape can be refined during implementation. Important part: API should not only return request acceptance when platform can later report success/configuration details.

Native / plugin flow

1. Expo plugin treats widgets with appIntent.parameters.length > 0 as configurable.
2. Expo plugin generates one configuration Activity, for example VoltraWidgetConfigurationActivity.
3. Generated appwidget-provider XML adds android:configure="<package>.VoltraWidgetConfigurationActivity" for configurable widgets.
4. On Android 12+, generated XML adds reconfigurable; it also adds configuration_optional when every parameter has a string default.
5. Activity reads AppWidgetManager.EXTRA_APPWIDGET_ID.
6. Activity resolves the widget provider/component to the Voltra widgetTypeId.
7. Activity mounts a secondary React Native root using the same app bundle and an AppRegistry component registered by Voltra, passing widgetTypeId, appWidgetId, defaults, and existing instance config as initial props.
8. Activity sets default result to RESULT_CANCELED, so backing out cancels the widget add according to Android rules when configuration is mandatory.
9. When JS calls completeAndroidWidgetConfiguration, native stores config under appWidgetId, updates the exact GlanceId, sets RESULT_OK with EXTRA_APPWIDGET_ID, and finishes.
10. When JS calls cancel/back, native sets RESULT_CANCELED with EXTRA_APPWIDGET_ID and finishes.

Why secondary root, not secondary RN instance

Use a second React Native root/surface on the existing ReactHost / ReactNativeHost, not a separate JS runtime.

Benefits:

• same Metro/release bundle
• no duplicated Hermes runtime
• shared TurboModule setup
• lower memory/cold-start cost
• standard AppRegistry.registerComponent model
• config screen can reuse app providers if the user wraps it that way

True separate RN instance would be much heavier: second JS runtime, second bundle eval, duplicated JS singletons, more native lifecycle risk, and more New Architecture maintenance.

Registration model

Voltra can internally register a stable native-facing root name, for example VoltraAndroidConfigurableWidgetRoot. registerAndroidConfigurableWidgetComponent stores the user component in JS and the Voltra root renders it.

Rough JS shape:

let ConfigurableWidgetComponent: React.ComponentType<AndroidConfigurableWidgetProps> | null = null

export function registerAndroidConfigurableWidgetComponent(
  component: React.ComponentType<AndroidConfigurableWidgetProps>
) {
  ConfigurableWidgetComponent = component
}

AppRegistry.registerComponent('VoltraAndroidConfigurableWidgetRoot', () => function Root(props) {
  if (!ConfigurableWidgetComponent) {
    return null
  }
  return <ConfigurableWidgetComponent {...props} />
})

The native Activity always mounts VoltraAndroidConfigurableWidgetRoot; user only provides the component.

Storage changes

Current Dynamic Widget config store is keyed by Voltra widget type id. Change stored overrides to use the Android instance id:

• defaults: widgetTypeId -> parameter defaults
• overrides: appWidgetId -> parameter values
• render merge: defaults[widgetTypeId] + overrides[appWidgetId]

VoltraClientGlanceWidget.provideGlance(context, glanceId) should resolve:

val appWidgetId = GlanceAppWidgetManager(context).getAppWidgetId(glanceId)
val configuration = VoltraConfigurationStore(context).get(widgetTypeId, appWidgetId)

Then pass that map into env.configuration for Hermes rendering.

Update path changes

Keep existing type-wide API for backward compatibility:

updateAndroidWidget(widgetTypeId, variants)

Add instance-targeted update API:

updateAndroidWidgetInstance(appWidgetId, variants)

Native should cache instance payloads separately and update only that appWidgetId. Type-wide payload remains fallback/default for all instances without instance-specific payload.

Server-driven widgets

Server requests should include both identifiers:

?widgetId=weather&appWidgetId=20&platform=android&theme=light

Worker/scheduler should fetch per placed instance when per-instance configuration exists or when a widget is declared configurable. Cache server payload by appWidgetId, not only by widget type id.

[Angelk90]

@V3RON : How should the voltra.config.ts configuration file be configured?

In this way:

import type { VoltraConfig } from 'voltra'

const config: VoltraConfig = {
  android: {
    widgets: [
      {
        id: 'weather',
        displayName: 'Weather',
        description: 'Show weather for a selected city',
        targetCellWidth: 3,
        targetCellHeight: 3,

        appIntent: {
          parameters: [
            {
              name: 'city',
              default: 'New York'
            },
            {
              name: 'units',
              default: 'metric'
            }
          ]
        }

      }
    ]
  }
}

export default config

[V3RON]

Agreed implementation approach

After reviewing the codebase and the Glance configuration contract, we've settled on the following scope and design.

Scope: Dynamic Widgets only

Per-instance configuration will be implemented only for Dynamic Widgets (client-rendered via the standalone Hermes runtime, VoltraClientGlanceWidget). These are the only widgets that can actually re-render on-device per instance — provideGlance runs per GlanceId with SizeMode.Exact, and the Hermes render(props, env) call happens on every render.

The legacy JSX-push API (updateAndroidWidget(widgetId, variants)) is going to be deprecated and cannot re-render natively, so:

• No per-instance payloads for server-rendered widgets.
• No changes to updateAndroidWidget, updateWidgetDirect, the refresh-button path, or WorkManager server updates. Ideas like updateAndroidWidgetInstance(appWidgetId, variants) and per-instance server fetches from the original proposal are out of scope.
• All generated configuration code (trampoline Activity, android:configure, widgetFeatures) is emitted only for clientRendered widgets, keeping Voltra dormant for apps without Dynamic Widgets (consistent with fix: keep Voltra Metro dormant without dynamic widgets #208).

Phase 1 — instance-scoped configuration

1. GlanceId → appWidgetId resolution. Glance has no public reverse mapping, so we enumerate getAppWidgetIds(provider) and match via getGlanceIdBy(appWidgetId) == glanceId (public API, no toString() parsing or reflection).
2. Layered configuration store. VoltraConfigurationStore gains an instance layer: voltra.config.<widgetTypeId>.<appWidgetId>.<key>. Read order: instance → legacy type-level key → code defaults (appIntent.parameters[].default, still keyed by widget type). Legacy type-level values act as a fallback layer, so existing users need no data migration and the current setWidgetConfiguration(widgetId, key, value) keeps working unchanged.
3. env.widgetInstanceId?: string. Exposed to the Hermes render on Android (the appWidgetId). Optional in the cross-platform type — iOS/WidgetKit has no OS-level instance id (instance identity there is implicit in the WidgetConfigurationIntent).
4. JS API (additive only). setWidgetConfiguration(widgetId, key, value, { instanceId? }) — instance writes update the stored value and re-render only that GlanceId (the triggerGlanceUpdate(context, widgetId, glanceId) overload already exists). getActiveWidgets() remains the instance-discovery API; its per-instance int id becomes the public instanceId.
5. Lifecycle cleanup. onDeleted in VoltraClientWidgetReceiver removes instance-scoped config (best-effort — hosts can recycle ids, and onDeleted isn't guaranteed on every launcher).

Phase 2 — deep-link configuration activity

Opt-in per widget in config, e.g. configuration: { deepLink: 'myapp://widget/edit' }:

• The Expo plugin generates a thin trampoline Activity per configurable Dynamic Widget: reads EXTRA_APPWIDGET_ID, validates it belongs to our package (getAppWidgetInfo — the launch intent is spoofable and the Activity must be android:exported="true"), calls setResult(RESULT_OK, intent with EXTRA_APPWIDGET_ID) immediately, fires ACTION_VIEW on the deep link with ?widgetId=<type>&instanceId=<appWidgetId> appended, and finishes.
• android:configure cannot point at the main RN Activity directly — the launcher starts the configure Activity with startActivityForResult and expects the RESULT_OK + EXTRA_APPWIDGET_ID contract, which the main Activity never fulfills. Hence the trampoline.
• Returning RESULT_OK up front means the widget is placed even if the user backs out of the in-app edit screen — acceptable because Dynamic Widgets always have code-level defaults. We pair this with widgetFeatures="reconfigurable|configuration_optional" (fine on our minSdk 31) so long-press → edit relaunches the same flow with the same appWidgetId.
• The app handles the deep link with normal RN Linking, shows its own UI, and persists via setWidgetConfiguration(widgetId, key, value, { instanceId }).

Deferred / skipped

• RN-hosted configuration Activity (secondary React Native root, registerWidgetConfigurationComponent, completeWidgetConfiguration() / cancelWidgetConfiguration()): to be revised later. The pattern is sound, but it drags in ReactHost cold-start inside a generated Activity, Expo vs bare divergence, and provider-wrapping caveats — a large surface for marginal gain over the deep-link flow. We'll revisit based on demand.
• onRestored id remapping: launcher backup/restore reassigns appWidgetIds; without remapping, restored instances fall back to type-level/default configuration. Documented as a known limitation for v1.
• Per-instance anything for the legacy widget API (see scope above).