feat(android): configure Dynamic Widgets per placed instance

[V3RON]

What is this?

This PR lets each placed Android Dynamic Widget hold its own configuration, so two placements of the same widget can show different data — different accounts, cities, lists, or filters. Until now Android configuration was scoped to the widget type, which meant every placement of a widget necessarily displayed the same values.

How does it work?

Configuration resolves in three layers, merged when the widget renders: code defaults declared as appIntent.parameters[].default, then values set for the widget type, then values set for one specific placed instance. The most specific layer wins.

Instance values are addressed by the Android appWidgetId and managed from inside your app:

• setWidgetInstanceConfiguration(appWidgetId, key, value) — or pass an object to write several keys as a single update, rather than one widget re-render per key.
• getWidgetInstanceConfiguration(appWidgetId) — reads back the fully merged configuration the widget actually sees, so a settings screen can open showing current values.
• getWidgetConfiguration(widgetId) — the same for the widget-type layer.
• clearWidgetInstanceConfiguration(appWidgetId) — hands an instance back to the widget-type and default values.

Writes are rejected for widgets belonging to another app and for server-rendered widgets, which never read env.configuration. When a user removes a widget from the home screen its instance values are deleted; because Android recycles appWidgetIds, this keeps a newly placed widget from inheriting a deleted one's configuration.

WidgetInfo from getActiveWidgets gains appWidgetId and widgetType. The existing widgetId and name fields still work, but are misleadingly named — widgetId is the instance id, not the widget's ID — so the new names are preferred.

Why is this useful?

Multiple instances of the same widget can finally be meaningfully different, which is the common reason to place a widget twice. Existing type-level configuration keeps working unchanged, and values stored under the older key format are migrated automatically.

The Android-native placement-time configuration flow — a configuration activity launched by the launcher when a widget is placed — was explored here and is deliberately left for a follow-up. Wiring android:configure changes placement semantics for every widget that declares appIntent parameters: the launcher discards a widget whose configuration activity does not complete. That flow is better delivered as a generated native form driven by the declared parameter schema, together with widgetFeatures="reconfigurable|configuration_optional" so placement is never blocked and users can reconfigure from the launcher.

[Angelk90]

@V3RON :

1. What's the point of having setWidgetConfiguration? If you have setWidgetInstanceConfiguration.
2. If I have two weather widgets installed on my home screen, one configured for London and one for New York, and the data displayed is about an hour old because it hasn't been updated yet, I want to be able to initiate an update directly from the app.

When the user opens the app and requests a refresh for all widgets (for example, by clicking a button), both widgets should receive the new weather data and automatically update, displaying the latest information for their respective cities, just like system weather apps like Samsung Weather.

Is this possible with the current code?

[Angelk90]

@V3RON: If I need to set multiple values, do I have to call setWidgetInstanceConfiguration multiple times?

 await setWidgetInstanceConfiguration(parsedAppWidgetId, 'theme', 'dark')
 await setWidgetInstanceConfiguration(parsedAppWidgetId, 'language', 'ko')
 await setWidgetInstanceConfiguration(parsedAppWidgetId, 'userId', '123')
 await completeWidgetConfiguration(parsedAppWidgetId)

I would prefer something like this:

setWidgetInstanceConfigurations(
  appWidgetId: number,
  values: Record<string, string>,
): Promise<void>;

setWidgetInstanceConfigurations(parsedAppWidgetId, {
  theme: "dark",
  language: "ko",
  userId: "123",
});

[V3RON]

@Angelk90 Batching is in — it landed after your comment, so you would not have seen it. Rather than a separate plural function, setWidgetInstanceConfiguration is overloaded:

// One key
await setWidgetInstanceConfiguration(appWidgetId, "theme", "dark")

// Several at once — your case
await setWidgetInstanceConfiguration(appWidgetId, {
  theme: "dark",
  language: "ko",
  userId: "123",
})

The object form is one bridge call, one DataStore transaction, and one widget re-render, instead of one of each per key. So it is what you asked for, just under the singular name.

On the naming specifically: I went with an overload rather than adding setWidgetInstanceConfigurations because two exported names differing only by a trailing s sit next to each other in autocomplete, and picking the wrong one still compiles. One name with two typed signatures avoids that, and there is only one thing to learn.

As for setWidgetConfiguration — it stays, and it is not redundant with the instance API:

• It is the only layer that can apply to placements that do not exist yet. There is no appWidgetId before a widget is placed, so "every future placement starts with these values" is not expressible per-instance.
• It is the right scope for genuinely app-wide settings — units, theme, locale — where a per-placement value would be the wrong model.
• It is existing public API; removing it would be a breaking change for anyone already using it.

The two layers compose: instance values shadow widget-type values, and clearWidgetInstanceConfiguration hands an instance back to the shared value.

Your second question, about refreshing both widgets from inside the app, deserves its own answer — replying to that separately.

[V3RON]

One note on scope, following up on my earlier reply.

Configuration in this PR applies to Dynamic (client-rendered) widgets only — setWidgetInstanceConfiguration and friends reject server-rendered widgets with an IllegalStateException. That is deliberate for now: server-rendered widgets never read env.configuration, so silently accepting writes that could never affect the render would be worse than failing loudly.

It is a statement about the current render path, not a permanent boundary. Making server-driven widgets configurable per instance is planned as a separate PR, where the merged configuration would be passed to the SSR endpoint so each placement can be rendered with its own values.

That work is larger than it first looks, which is why it is not bundled here. Today both the server URL (server_url_<widgetId>) and the cached payload (KEY_JSON_PREFIX + widgetId) are keyed by widget type, so per-instance responses need an instance-keyed storage layer of their own — plus scheduling, cleanup on delete, and recycled-appWidgetId safety, mirroring what this PR does for configuration. Changing a configuration value would also need to trigger a refetch rather than a re-render from cache.

Nothing in this PR forecloses that; the instance-id plumbing added here is the groundwork for it.

[Angelk90]

@V3RON : One thing I don't understand, you say: PR applies to dynamic (client-rendered) widgets only

But with this PR or the current repository, if I have a widget and want it to update itself every 30 minutes, is it possible to do so?
Example: I created a weather widget, I have the widget component created, and it needs to get information from a nodeJs/php API that returns the JSON info every 30 minutes to update the data.
Is it possible to do this at this point?

I'm talking without using server-rendered.

If I haven't explained myself well, I'll try to explain it again.