requestPinWidget static method

Future<bool> requestPinWidget(
  1. String widgetName
)

Asks the launcher to show its "add widget" dialog for widgetName, letting a user place a widget without leaving your app.

This is the single biggest lever on widget adoption: most users never discover the launcher's widget picker on their own.

Returns whether the dialog was shown — not whether the user accepted; Android does not report the outcome. Detect actual placement by watching for the widget's first update.

Android only (API 26+, and only on launchers that support pinning). iOS exposes no equivalent — Apple requires the user to go through the widget gallery — so this returns false there and you should fall back to on-screen instructions. Check canRequestPinWidget first.

if (await MosaicBridge.canRequestPinWidget()) {
  await MosaicBridge.requestPinWidget('News');
} else {
  showDialog(...); // "Long-press the home screen, tap Widgets…"
}

Implementation

static Future<bool> requestPinWidget(String widgetName) async {
  try {
    return await _channel.invokeMethod<bool>(
          'requestPinWidget',
          {'widgetName': widgetName},
        ) ??
        false;
  } on MissingPluginException {
    return false;
  }
}