Building App widget for the Cookpad Android app

Widgets display condensed information of an app’s most important data on the device's home screen, which links to richer details within the app.

Widgets were introduced in 2008 in Android. Their capability has come far since then. At Cookpad, we decided to leverage the Android OS widget to let our users customise their home screen with direct access to their most important recipes. Along with entry points to organize their saved recipes.

At a high level, each widget is a BroadcastReceiver paired with XML metadata describing the widget details. The framework communicates with the widget through broadcast intents to request updates.

Here is the official guide on how to build a widget. This post however can serve you as a practical guideline when building one.

Design and Style

• Highlight the most important information or action of your app in the widget. The main entry point for the Cookpad app is the recipe itself, where users can look at the recipe details, send cooksnaps, and interact with other home cooks.

• Choose the right widget style.
  Information widget — shows a few elements of importance to a user such as weather or sports scores.
  Collection widget — displays multiple elements of the same type, such as a collection of articles, pictures, or news. Focus on browsing items.
  Control widget — Control widgets display frequently used functions example media control buttons on your favorite media player app.
  Hybrid widget: Many widgets are hybrid, which combines the elements of the above styles.
• Once you know the widget style next is to decide the widget size. Do you want it to be fixed or resizable? For resizable widgets, plan how the views for your widget should adapt to different sizes.

• Layouts: App Widget layouts are based on RemoteViews, which do not support every kind of layout. See the supported list of layouts.
• Decide if you want one widget or multiple. It is possible to assign the ‘Preview Image’ to the widget. This is especially important when you have more than one widget. This makes it easier for users to find the right widget. If there is no preview image, the default app icon is displayed.
• If your widget has complex view states, it is best to update the widget view outside of the ‘WigetProvider’ class by getting the ‘AppWidgetManager’ instance and calling updateAppWidget() for each widget Id.

Behavior

Update frequency: The updatePeriodMillis attribute defines how often the App Widget framework should request an update from the AppWidgetProvider by calling the onUpdate() method. The actual update is not guaranteed to occur exactly on time with this value and we suggest updating as infrequently as possible. Updates requested with updatePeriodMillis will not be delivered more than once every 30 minutes.

If the device is asleep when it is time for an update, then the device will wake up to perform the update. If you don’t update more than once per hour, this won’t cause significant problems for battery life.

1. Manual update — It is tempting to refresh the widget via subscribing to an event stream (event bus). This potentially could cause memory leaks as an active stream could be observed forever until the widget is removed. The best approach is to update the widget by broadcast intent.

• Configuration: It is possible to provide a screen to configure settings when the widget is added by creating a configuration Activity. This screen will be automatically launched by the App Widget, which enables the user to configure available settings. Example settings are widget colour (switch between dark/light mode), size, update period frequency, etc.
• Loading state — If your widget depends on calling APIs or need to perform heavy IO operations like generating bitmaps, it's best to add a loading state.

Error Handling: Handle error scenario gracefully with the error view state. The ‘retry’ button is important as to rectify the issue user has to delete and add the widget again, which is inconvenient. The retry button updates the widget, which will refresh data and the views.

Navigation:

Wiget provides quick navigation to the detail screens within your app.

1. Decide if you need to maintain the back stack when coming from the widget.

2. Add analytics to find out how many users are coming via Widget.

3. Handling guest mode. If your app requires the user to logged-in state to use the widget, consider redirecting the user to the login screen, and once logged in refresh the widget. Also, refresh the widget on sign out.

Widget Pinning :

From Android 8 onwards, the user can pin the widget from within the app.
This reduces the friction of searching and adding a widget manually by the user. This increases widget visibility significantly.

Testing

• Test your widget in RTL mode and how it adapts to different home grid settings. On many devices, it’s possible to change home grid settings.
• Testing widget in the emulator. You can search for an app, called WidgetPreview on emulator (API 26 or lower) and long-pressing the app icon on later API versions, to add a widget. On physical devices pinch the home screen and select widgets or touch and hold empty space on the home screen.

We hope these guidelines will help you build a widget and treat them as a part of your true android app experience.