Android Home Screen Widgets

ZestSSH provides a Quick Connect home screen widget for Android that lets you connect to your servers directly from the home screen without opening the app.

Quick Connect Widget

The widget displays up to 4 connections as quick-connect buttons. Tapping a button launches ZestSSH and connects directly to that server.

What’s Displayed

Each connection button shows:

• Connection label (display name)
• Host address
• Port number
• Connection ID (used internally for routing)

Connection Limit

The widget always shows the first 4 connections from your connection list. If you have fewer than 4 connections, only those are displayed. If you have more, only the first 4 (by sort order) appear.

How It Works

Data Flow

1. Flutter side: The WidgetService writes a JSON list of connection data to SharedPreferences under the key widget_connections.
2. Native side: The Android widget reads from SharedPreferences to render the quick-connect buttons.
3. Tap action: Tapping a button sends an intent with the connection ID, which the app receives via the deep link handler and initiates the connection.

Method Channel

Communication between Flutter and the native widget uses the method channel com.affluentlabs.zestssh/widget:

Method	Direction	Purpose
updateWidget	Flutter -> Native	Tell Android to refresh the widget after data changes

Data Format

The JSON stored in SharedPreferences is an array of objects:

[
  {"id": "abc123", "label": "Production", "host": "prod.example.com", "port": 22},
  {"id": "def456", "label": "Staging", "host": "staging.example.com", "port": 22}
]

Auto-Refresh

The widget data is updated automatically whenever connections change:

• Adding a new connection
• Editing a connection (name, host, port)
• Deleting a connection
• Reordering connections

The WidgetService.updateConnections() method is called with the current connections list, which writes the JSON and invokes updateWidget on the native side to trigger a widget refresh.

Error Handling

Widget updates are fire-and-forget. If the method channel is not registered (e.g., the native widget component is not compiled), the MissingPluginException is caught silently. Other errors are logged but do not affect app operation.

Adding the Widget

1. Long-press on your Android home screen.
2. Select Widgets.
3. Find ZestSSH in the widget list.
4. Drag the Quick Connect widget to your home screen.
5. The widget populates with your first 4 connections.

iOS Widgets

On iOS, ZestSSH includes a WidgetKit extension (located at ios/ZestSSHWidget/). The WidgetService calls reloadWidgets on the method channel com.affluentlabs.zestssh/widget to trigger a widget timeline reload when connection data changes.