Generierte Vorschauen zur Widget-Auswahl hinzufügen

Mit generierten Widget-Vorschauen können Sie dynamische, personalisierte Vorschauen für Ihre Widgets erstellen, die genau widerspiegeln, wie sie auf dem Startbildschirm eines Nutzers angezeigt werden. Sie werden über eine Push-API bereitgestellt. Das bedeutet, dass Ihre App die Vorschau zu jedem Zeitpunkt während ihres Lebenszyklus bereitstellt, ohne eine explizite Anfrage vom Widget-Host zu erhalten.

In diesem Leitfaden wird beschrieben, wie Sie Vorschauen für Glance-basierte Widgets bereitstellen. Wenn Ihr Widget mit RemoteViews implementiert ist, lesen Sie den Abschnitt Vorschauen zur Widget-Auswahl hinzufügen.

Um die Widget-Auswahl für Glance-Widgets in Ihrer App zu verbessern, stellen Sie eine generierte Widget-Vorschau mit GlanceAppWidget.providePreview auf Geräten mit Android 15 und höher bereit und geben Sie ein previewImage für frühere Versionen und als Fallback auf Geräten mit Android 15 und höher an, wenn keine generierte Vorschau verfügbar ist.

Weitere Informationen finden Sie auf YouTube unter Enrich your app with live updates and widgets.

App für generierte Widget-Vorschauen einrichten

Wenn Sie generierte Widget-Vorschaubilder auf einem Gerät mit Android 15 oder höher anzeigen möchten, müssen Sie zuerst den compileSdk-Wert in der Moduldatei build.gradle auf 35 oder höher festlegen, damit Sie dem Widget-Picker RemoteViews zur Verfügung stellen können.

Apps können dann setWidgetPreview in GlanceAppWidgetManager verwenden. Um Missbrauch zu verhindern und Bedenken hinsichtlich der Systemintegrität zu minimieren, ist setWidgetPreview eine API mit Ratenbegrenzung. Das Standardlimit liegt bei etwa zwei Anrufen pro Stunde.

Aktualisierte Vorschau mit Jetpack Glance generieren

Gehen Sie für mit Jetpack Glance erstellte Widgets so vor:

1. Überschreiben Sie die Funktion GlanceAppWidget.providePreview, um den zusammensetzbaren Inhalt für die Vorschau bereitzustellen. Laden Sie wie in provideGlance die Daten Ihrer App und übergeben Sie sie an die Content-Composable-Funktion des Widgets, damit in der Vorschau korrekte Daten angezeigt werden. Im Gegensatz zu provideGlance handelt es sich hierbei um eine einzelne Komposition ohne Neukomposition oder Effekte.

2. Rufen Sie GlanceAppWidgetManager.setWidgetPreviews auf, um die Vorschau zu generieren und zu veröffentlichen.

Es gibt keinen Callback vom System, um Vorschauen bereitzustellen. Ihre App muss also entscheiden, wann setWidgetPreviews aufgerufen werden soll. Die Aktualisierungsstrategie hängt vom Anwendungsfall Ihres Widgets ab:

• Wenn das Widget statische Informationen enthält oder eine Schnellaktion ist, legen Sie die Vorschau beim ersten Starten der App fest.
• Sie können die Vorschau festlegen, sobald Ihre App Daten hat, z. B. nach der Anmeldung eines Nutzers oder der Ersteinrichtung.
• Sie können einen regelmäßigen Task einrichten, um die Vorschauen in einem bestimmten Rhythmus zu aktualisieren.

Fehlerbehebung bei generierten Vorschauen

Ein häufiges Problem ist, dass nach dem Generieren einer Vorschau Bilder, Symbole oder andere Composables im Vergleich zur Drop-Größe des Widgets im Vorschaubild fehlen. Diese Drop-Größe wird durch targetCellWidth und targetCellHeight (falls angegeben) oder durch minWidth und minHeight in der Datei mit Informationen zum App-Widget-Anbieter definiert.

Das liegt daran, dass Android standardmäßig nur Composables rendert, die bei der Mindestgröße des Widgets sichtbar sind. Mit anderen Worten: Android setzt previewSizeMode standardmäßig auf SizeMode.Single. Dazu werden android:minHeight und android:minWidth im XML-Code für App-Widget-Provider verwendet, um zu bestimmen, welche Composables gezeichnet werden sollen.

Um das Problem zu beheben, überschreiben Sie previewSizeMode in Ihrem GlanceAppWidget und legen Sie es auf SizeMode.Responsive fest. Geben Sie dazu eine Reihe von DpSize-Werten an. So wird Android mitgeteilt, welche Layoutgrößen für die Vorschau gerendert werden müssen, damit alle Elemente richtig angezeigt werden.

Für bestimmte Formfaktoren optimieren Geben Sie eine oder zwei Größen an, die mit der Mindestgröße beginnen und den Breakpoints Ihres Widgets entsprechen. Geben Sie mindestens ein previewImage zur Abwärtskompatibilität an. Die entsprechenden Mindest-DP-Werte für verschiedene Rastergrößen finden Sie in den Richtlinien für das Widget-Design.

Abwärtskompatibilität mit Widget-Vorschauen

Wenn Sie möchten, dass in der Widget-Auswahl auf Geräten mit einer Version unter Android 15 Vorschauen Ihres Widgets angezeigt werden, oder als Fallback für generierte Vorschauen unter Android 15 und höher, geben Sie das Attribut previewImage an.

Wenn Sie das Aussehen des Widgets ändern, aktualisieren Sie das Vorschaubild.