feat(build): support custom <provider> entries in AndroidManifest via pyproject.toml (#6559)

FeodorFitsner · web-flow · commit 95d105d45649 · 2026-06-06T13:23:47.000-07:00
* feat(build): support custom <provider> entries in AndroidManifest via pyproject.toml Add `[tool.flet.android.provider]` for declaring custom `<provider>` entries on the generated `AndroidManifest.xml`. Each table key is the provider's `android:name`; entries become `android:<key>="<value>"` attributes on the generated element. A reserved `meta_data` sub-table emits nested `<meta-data>` children — scalar values render as `android:value="..."`, inline-table values render as `android:<k>="<v>"` so `android:resource="@xml/..."` works. `false` / `{}` skip the entry; `true` and invalid value types fail the build with a clear error. Booleans are normalized to lowercase `"true"/"false"` since Android XML requires them lowercase. The built-in `androidx.core.content.FileProvider` block is unchanged; user-declared providers must not reuse its authorities. Closes #6556. * docs(changelog): reference PR #6559 in the provider entry
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ### Improvements
 
 * Allow `[tool.flet.android.permission]` values to be TOML inline tables in addition to booleans — each `key = "value"` entry adds an `android:<key>="<value>"` attribute to the generated `<uses-permission>` element, unlocking modifiers like `android:maxSdkVersion` and `android:usesPermissionFlags` that real-world Android permissions (e.g. Bluetooth LE) require. The boolean form and the `--android-permissions` CLI flag are unchanged; a non-empty inline table is always emitted, an empty table (`{}`) is treated as `false`, and invalid value types fail the build with a clear error ([#6550](https://github.com/flet-dev/flet/issues/6550), [#6551](https://github.com/flet-dev/flet/pull/6551)) by @FeodorFitsner.
+* Add `[tool.flet.android.provider]` for declaring custom `<provider>` entries in the generated `AndroidManifest.xml`. Each table key is the provider's `android:name`; entries become `android:<key>="<value>"` attributes on the generated element. A reserved `meta_data` sub-table emits nested `<meta-data>` children (scalar values render as `android:value="…"`; inline-table values render as `android:<k>="<v>"` so `android:resource="@xml/…"` works). `false` / `{}` skip the entry; `true` and invalid value types fail the build with a clear error. The built-in `androidx.core.content.FileProvider` block is unchanged ([#6556](https://github.com/flet-dev/flet/issues/6556), [#6559](https://github.com/flet-dev/flet/pull/6559)) by @FeodorFitsner.
 * Upgrade the bundled Pyodide runtime in the `flet build web` template from `0.27.5` to `0.27.7` (includes `micropip` `0.9.0`) ([#6549](https://github.com/flet-dev/flet/pull/6549)) by @FeodorFitsner.
 * Drop generated `web/canvaskit/` build artifacts (`canvaskit.js`/`.wasm`/`.symbols` and the `chromium/` and `skwasm`/`skwasm_st` variants) from the `flet build web` template — these are produced by the Flutter web build and should not have been committed into the cookiecutter template ([#6549](https://github.com/flet-dev/flet/pull/6549)) by @FeodorFitsner.
 * Cache the downloaded `flet-build-template.zip` across builds. The build template is bound to an exact Flet version and is immutable, so on every `flet build` / `flet debug` after the first, the CLI now uses a previously-downloaded zip from `$FLET_CACHE_DIR/build-template/v<flet-version>/` (defaulting to `~/.flet/cache/build-template/v<flet-version>/`) instead of re-fetching it via cookiecutter. The CLI also exports `FLET_CACHE_DIR` into the child Gradle process, so `serious_python_android` >= 1.0.1 lands its Python dist tarballs (`python-android-dart-<py>-<abi>.tar.gz`) in the same cache root by default — fixing the multi-minute "Creating app shell" / `downloadDistArchive_*` delay on every Android debug build. Custom `--template` URLs and the local-dev template path are unchanged ([#6555](https://github.com/flet-dev/flet/discussions/6555), [#6558](https://github.com/flet-dev/flet/pull/6558)) by @FeodorFitsner.
diff --git a/sdk/python/examples/apps/flet_build_test/pyproject.toml b/sdk/python/examples/apps/flet_build_test/pyproject.toml
@@ -94,6 +94,9 @@ path = "src"
 [tool.flet.android.meta_data]
 "com.google.android.gms.ads.APPLICATION_ID" = "ca-app-pub-3940256099942544~3347511713"
 
+[tool.flet.android.provider]
+"rikka.shizuku.ShizukuProvider" = { authorities = "${applicationId}.shizuku", multiprocess = "false", enabled = "true", exported = "true", permission = "android.permission.INTERACT_ACROSS_USERS_FULL" }
+
 [tool.flet.ios.info]
 GADApplicationIdentifier = "ca-app-pub-3940256099942544~3347511713"
 
diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py
@@ -826,6 +826,7 @@ def setup_template_data(self):
             "android.hardware.touchscreen": False,
         }
         android_meta_data = {}
+        android_providers = {}
 
         # merge values from "--permissions" arg:
         for p in (
@@ -974,6 +975,88 @@ def setup_template_data(self):
             else:
                 self.cleanup(1, f"Invalid Android meta-data option: {p}")
 
+        android_providers = merge_dict(
+            android_providers,
+            self.get_pyproject("tool.flet.android.provider") or {},
+        )
+
+        def _xml_attr_value(v):
+            # Android XML expects lowercase booleans.
+            if isinstance(v, bool):
+                return "true" if v else "false"
+            return v
+
+        normalized_providers = {}
+        for key, value in android_providers.items():
+            if value is False or value == {}:
+                continue
+            if value is True:
+                self.cleanup(
+                    1,
+                    f"Invalid Android provider value for {key}: 'true' is not "
+                    "supported. Use an inline table of attributes, or 'false' "
+                    "to skip.",
+                )
+            if not isinstance(value, dict):
+                self.cleanup(
+                    1,
+                    f"Invalid Android provider value for {key}: "
+                    f"{type(value).__name__}. Expected boolean or inline table.",
+                )
+            normalized = {}
+            for ak, av in value.items():
+                if ak == "name":
+                    self.cleanup(
+                        1,
+                        f"Invalid Android provider attribute for {key}: "
+                        "'name' is reserved and is taken from the table key.",
+                    )
+                if ak == "meta_data":
+                    if not isinstance(av, dict):
+                        self.cleanup(
+                            1,
+                            f"Invalid Android provider meta_data for {key}: "
+                            f"{type(av).__name__}. Expected inline table.",
+                        )
+                    normalized_meta = {}
+                    for mk, mv in av.items():
+                        if isinstance(mv, (str, bool, int, float)):
+                            normalized_meta[mk] = _xml_attr_value(mv)
+                            continue
+                        if isinstance(mv, dict):
+                            normalized_attrs = {}
+                            for attr_key, attr_value in mv.items():
+                                if not isinstance(attr_value, (str, bool, int, float)):
+                                    self.cleanup(
+                                        1,
+                                        f"Invalid Android provider meta-data "
+                                        f"attribute value for "
+                                        f"{key}.meta_data.{mk}.{attr_key}: "
+                                        f"{type(attr_value).__name__}. "
+                                        "Expected string, boolean, or number.",
+                                    )
+                                normalized_attrs[attr_key] = _xml_attr_value(attr_value)
+                            normalized_meta[mk] = normalized_attrs
+                            continue
+                        self.cleanup(
+                            1,
+                            f"Invalid Android provider meta-data value for "
+                            f"{key}.meta_data.{mk}: {type(mv).__name__}. "
+                            "Expected string, boolean, number, or inline table.",
+                        )
+                    normalized["meta_data"] = normalized_meta
+                    continue
+                if not isinstance(av, (str, bool, int, float)):
+                    self.cleanup(
+                        1,
+                        f"Invalid Android provider attribute value for "
+                        f"{key}.{ak}: {type(av).__name__}. "
+                        "Expected string, boolean, or number.",
+                    )
+                normalized[ak] = _xml_attr_value(av)
+            normalized_providers[key] = normalized
+        android_providers = normalized_providers
+
         deep_linking_scheme = (
             self.get_pyproject("tool.flet.ios.deep_linking.scheme")
             if self.package_platform == "iOS"
@@ -1126,6 +1209,7 @@ def setup_template_data(self):
                 "android_permissions": android_permissions,
                 "android_features": android_features,
                 "android_meta_data": android_meta_data,
+                "android_providers": android_providers,
                 "deep_linking": {
                     "scheme": deep_linking_scheme,
                     "host": deep_linking_host,
diff --git a/sdk/python/templates/build/{{cookiecutter.out_dir}}/android/app/src/main/AndroidManifest.xml b/sdk/python/templates/build/{{cookiecutter.out_dir}}/android/app/src/main/AndroidManifest.xml
@@ -61,6 +61,11 @@
                 android:name="android.support.FILE_PROVIDER_PATHS"
                 android:resource="@xml/provider_paths" />
         </provider>
+        <!-- flet: provider {% for k, v in cookiecutter.options.android_providers.items() %} {% if v %} -->
+        <provider android:name="{{ k }}"{% for ak, av in v.items() if ak != 'meta_data' %} android:{{ ak }}="{{ av }}"{% endfor %}{% if not v.get('meta_data') %} />{% else %}>
+            {% for mk, mv in v.meta_data.items() %}{% if mv is mapping %}<meta-data android:name="{{ mk }}"{% for attr_key, attr_value in mv.items() %} android:{{ attr_key }}="{{ attr_value }}"{% endfor %} />{% else %}<meta-data android:name="{{ mk }}" android:value="{{ mv }}" />{% endif %}
+            {% endfor %}</provider>{% endif %}
+        <!-- flet: end of provider {% endif %} {% endfor %} -->
         <!-- Don't delete the meta-data below.
              This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
         <meta-data
diff --git a/website/docs/publish/android.md b/website/docs/publish/android.md
@@ -424,6 +424,96 @@ the `pyproject.toml` example above will be translated accordingly into this:
 ```
 </details>
 
+### Providers
+
+A content provider component that supplies app data to other apps or components.
+More information [here](https://developer.android.com/guide/topics/manifest/provider-element).
+
+Each provider is declared as a TOML table whose key is the provider's
+`android:name` (the fully-qualified class name). The table's entries become
+extra `android:<key>="<value>"` attributes on the generated `<provider>`
+element. A reserved `meta_data` sub-table emits nested `<meta-data>` children
+inside the provider.
+
+See also:
+
+- [`<provider>` element](https://developer.android.com/guide/topics/manifest/provider-element)
+
+#### Resolution order
+
+Its value is determined in the following order of precedence:
+
+1. `[tool.flet.android.provider]`
+
+#### Supported value forms
+
+The value for each provider must be a TOML inline table or sub-table of
+attributes. A value of `false` skips the entry entirely; `true` is not
+accepted (a `<provider>` with no attributes is meaningless). An empty table
+`{}` is also treated as `false`.
+
+Attribute values must be strings, booleans, or numbers — they are written
+verbatim into the manifest. The `name` key is reserved (the `android:name`
+comes from the table key).
+
+The reserved `meta_data` sub-table emits `<meta-data>` children. Each
+sub-entry's key is the `android:name`; the value can be either:
+
+- a scalar (string/bool/number) — rendered as `android:value="…"`, or
+- an inline table — its entries become `android:<key>="<value>"` attributes
+  on the `<meta-data>` element (useful for `android:resource="@xml/…"`).
+
+#### Example
+
+<Tabs groupId="pyproject-toml">
+<TabItem value="pyproject-toml" label="pyproject.toml">
+```toml
+[tool.flet.android.provider]
+"rikka.shizuku.ShizukuProvider" = { authorities = "${applicationId}.shizuku", multiprocess = "false", enabled = "true", exported = "true", permission = "android.permission.INTERACT_ACROSS_USERS_FULL" }
+
+[tool.flet.android.provider."com.example.MyProvider"]
+authorities = "${applicationId}.myprovider"
+exported = false
+grantUriPermissions = true
+
+[tool.flet.android.provider."com.example.MyProvider".meta_data]
+"android.support.FILE_PROVIDER_PATHS" = { resource = "@xml/file_paths" }
+"some.other.key" = "some-value"
+```
+</TabItem>
+</Tabs>
+<details>
+<summary>Template translation</summary>
+
+In the [`AndroidManifest.xml`](index.md#build-template),
+the `pyproject.toml` example above will be translated accordingly into this:
+
+```xml
+<application>
+    <provider android:name="rikka.shizuku.ShizukuProvider"
+              android:authorities="${applicationId}.shizuku"
+              android:multiprocess="false"
+              android:enabled="true"
+              android:exported="true"
+              android:permission="android.permission.INTERACT_ACROSS_USERS_FULL" />
+    <provider android:name="com.example.MyProvider"
+              android:authorities="${applicationId}.myprovider"
+              android:exported="false"
+              android:grantUriPermissions="true">
+        <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" />
+        <meta-data android:name="some.other.key" android:value="some-value" />
+    </provider>
+</application>
+```
+</details>
+
+:::note
+Flet already declares a built-in `androidx.core.content.FileProvider` with
+authorities `${applicationId}.provider`. Declaring another provider that
+uses the same authorities will cause the Android manifest merger to fail —
+pick a different `android:authorities` value for your custom provider.
+:::
+
 ### Features
 
 A hardware or software feature that is used by the application.
