iiEsaywebUIapp/docs/android-widget-setup.md

Android Widget Setup

The Android home screen widget is automatically included in the app build. This document describes the implementation details.

Overview

The widget uses Material 3 / Material You design with dynamic colors on Android 12+ (API 31+).

Widget Design (Native Android)

┌─────────────────────────────────────┐
│  ✨  Ask Conduit                    │  ← Primary color (dynamic)
│                                     │
├───────────┬───────────┬─────────────┤
│  📷       │  🖼️       │  📋        │
│ Camera    │ Photos    │ Clipboard   │  ← Secondary container
└───────────┴───────────┴─────────────┘

Material You (Android 12+)

• Primary button: System accent color (system_accent1_600)
• Secondary buttons: Secondary container color (system_accent2_100)
• Background: Neutral surface color (system_neutral1_10)
• Icons: Tinted with system_accent1_700

Fallback (Android 11 and below)

• Primary button: Material 3 default purple (#6750A4)
• Secondary buttons: Light purple container (#E8DEF8)
• Background: Near-white surface (#FFFBFE)

Files Structure

android/app/src/main/
├── kotlin/.../ConduitWidgetProvider.kt   # Widget logic
├── res/
│   ├── layout/
│   │   └── conduit_widget.xml            # Widget layout
│   ├── drawable/
│   │   ├── widget_background.xml         # Surface background
│   │   ├── widget_button_primary.xml     # Primary button
│   │   ├── widget_button_secondary.xml   # Secondary buttons
│   │   ├── ic_widget_camera.xml          # Camera icon
│   │   ├── ic_widget_photos.xml          # Photos icon
│   │   ├── ic_widget_clipboard.xml       # Clipboard icon
│   │   └── widget_preview.xml            # Widget picker preview
│   ├── drawable-v31/                     # Material You overrides
│   │   └── (same files with dynamic colors)
│   ├── values/
│   │   ├── colors.xml                    # Light mode colors
│   │   ├── dimens.xml                    # Widget dimensions
│   │   └── strings.xml                   # Widget strings
│   ├── values-night/
│   │   └── colors.xml                    # Dark mode colors
│   └── xml/
│       └── conduit_widget_info.xml       # Widget metadata
└── AndroidManifest.xml                   # Widget receiver registration

Deep Link Handling

The widget uses homewidget:// URL scheme:

Action	URL
New Chat	homewidget://new_chat
Camera	homewidget://camera
Photos	homewidget://photos
Clipboard	homewidget://clipboard

Widget Configuration

The widget is configured in res/xml/conduit_widget_info.xml:

• Min size: 250x110dp (3x2 cells)
• Resizable: Horizontal and vertical
• Category: Home screen
• Update period: Never (static widget)

Testing

1. Build and install the debug APK:

   flutter build apk --debug
   flutter install
   

2. Long press on home screen

3. Tap "Widgets"

4. Search for "Conduit"

5. Drag widget to home screen

Customization

Changing the accent color

The widget automatically picks up the system's Material You palette on Android 12+. On older versions, modify the fallback colors in values/colors.xml:

<color name="widget_primary_fallback">#YOUR_COLOR</color>

Changing widget size

Modify res/xml/conduit_widget_info.xml:

<appwidget-provider
    android:minWidth="250dp"
    android:minHeight="110dp"
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    ...
/>

Troubleshooting

Widget not appearing

• Ensure the app was installed (not just built)
• Try restarting the home launcher
• Check that ConduitWidgetProvider is registered in AndroidManifest.xml

Colors not updating on theme change

• Widget colors are set at creation time
• User needs to re-add widget after theme change
• Or trigger update via HomeWidget.updateWidget() from Flutter