Datenanbieter-Apps geben Informationen zu Zusatzfunktionen für das Zifferblatt aus und geben Felder an, die Text, Strings, Bilder und Zahlen enthalten.
Ein Datenanbieterdienst erweitert
ComplicationProviderService
, um nützliche Informationen direkt auf einem Zifferblatt bereitzustellen.
Datenanbieterprojekt erstellen
So erstellen Sie in Android Studio ein Projekt für Ihre Datenanbieter-App:
- Klicken Sie auf Datei > Neu > Neues Projekt.
- Klicken Sie im Fenster Projektvorlage auf den Tab „Wear OS“, wählen Sie Keine Aktivität aus und klicken Sie auf Weiter.
- Benennen Sie Ihr Projekt im Fenster Projekt konfigurieren, geben Sie die Standardprojektinformationen ein und klicken Sie auf Fertigstellen.
- Android Studio erstellt ein Projekt mit einem App-Modul für Ihren Datenanbieter. Weitere Informationen zu Projekten in Android Studio findest du unter Projekt erstellen.
- Starten Sie Ihre Datenanbieteranwendung, indem Sie eine neue Klasse erstellen, die
BroadcastReceiver
erweitert. Der Zweck dieser Klasse besteht darin, vom Wear OS-System auf Anfragen zur Aktualisierung von Zusatzfunktionen zu warten. Erstellen Sie außerdem eine neue Klasse, dieComplicationProviderService
erweitert, um Daten bereitzustellen, wenn diese durch entsprechende Zusatzfunktionen angefordert werden. Weitere Informationen finden Sie hier:- Methode für Aktualisierungsanfragen implementieren
- Die Klassen
ComplicationTapBroadcastReceiver
undCustomComplicationProviderService
im folgenden Codelab: Daten für Zusatzfunktionen von Zifferblatt unter Wear OS verfügbar machen ComplicationToggleReceiver
,LongTextProviderService
und andere Klassen im Testsuite-Beispiel
Hinweis: Das Hinzufügen einer Aktivität für Ihren Datenanbieter ist optional. Angenommen, Sie möchten eine Aktivität, die nur gestartet wird, wenn der Nutzer auf eine Zusatzfunktion tippt.
Methode für Aktualisierungsanfragen implementieren
Wenn Daten für Zusatzfunktionen benötigt werden, sendet das Wear OS-System Aktualisierungsanfragen an deinen Datenanbieter. Die Anfragen werden von deinem
BroadcastReceiver
empfangen. Um auf die Aktualisierungsanfragen zu antworten, muss Ihr Datenanbieter die Methode
onComplicationUpdate()
der Klasse ComplicationProviderService
implementieren.
Das Wear OS-System ruft onComplicationUpdate()
auf, wenn es Daten von deinem Anbieter benötigt, z. B. wenn eine Zusatzfunktion, die deinen Anbieter verwendet, aktiv wird oder wenn ein bestimmter Zeitraum verstrichen ist.
Es übergibt ein
ComplicationManager
-Objekt als Parameter an onComplicationUpdate
, mit dem Daten zurück an das System gesendet werden.
Hinweis:Wenn die App deines Datenanbieters Daten bereitstellt, empfängt das Zifferblatt die von dir gesendeten Rohdaten, damit die Informationen erfasst werden können.
Das folgende Code-Snippet zeigt eine Beispielimplementierung der Methode onComplicationUpdate
:
Kotlin
override fun onComplicationUpdate( complicationId: Int, dataType: Int, complicationManager: ComplicationManager) { Log.d(TAG, "onComplicationUpdate() id: $complicationId") // Used to create a unique key to use with SharedPreferences for this complication. val thisProvider = ComponentName(this, javaClass) // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs. val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0) val number = preferences.getInt( ComplicationTapBroadcastReceiver.getPreferenceKey( thisProvider, complicationId), 0) val numberText = String.format(Locale.getDefault(), "%d!", number) var complicationData: ComplicationData? = null when (dataType) { ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT) .setShortText(ComplicationText.plainText(numberText)) .build() else -> if (Log.isLoggable(TAG, Log.WARN)) { Log.w(TAG, "Unexpected complication type $dataType") } } if (complicationData != null) { complicationManager.updateComplicationData(complicationId, complicationData) } else { // If no data is sent, we still need to inform the ComplicationManager, so // the update job can finish and the wake lock isn't held any longer. complicationManager.noUpdateRequired(complicationId) } }
Java
@Override public void onComplicationUpdate( int complicationId, int dataType, ComplicationManager complicationManager) { Log.d(TAG, "onComplicationUpdate() id: " + complicationId); // Used to create a unique key to use with SharedPreferences for this complication. ComponentName thisProvider = new ComponentName(this, getClass()); // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs. SharedPreferences preferences = getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0); int number = preferences.getInt( ComplicationTapBroadcastReceiver.getPreferenceKey( thisProvider, complicationId), 0); String numberText = String.format(Locale.getDefault(), "%d!", number); ComplicationData complicationData = null; switch (dataType) { case ComplicationData.TYPE_SHORT_TEXT: complicationData = new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT) .setShortText(ComplicationText.plainText(numberText)) .build(); break; default: if (Log.isLoggable(TAG, Log.WARN)) { Log.w(TAG, "Unexpected complication type " + dataType); } } if (complicationData != null) { complicationManager.updateComplicationData(complicationId, complicationData); } else { // If no data is sent, we still need to inform the ComplicationManager, so // the update job can finish and the wake lock isn't held any longer. complicationManager.noUpdateRequired(complicationId); } }
Manifestdeklarationen und Berechtigungen
Datenanbieter-Apps müssen in ihrem App-Manifest bestimmte Deklarationen enthalten, damit sie vom Android-System als Datenanbieter behandelt werden. In diesem Abschnitt werden die erforderlichen Einstellungen für Datenanbieteranwendungen erläutert.
Deklarieren Sie im Manifest Ihrer App den Dienst und fügen Sie einen Intent-Filter für Updateanfrageaktionen hinzu.
Das Manifest muss den Dienst außerdem schützen. Dazu wird die Berechtigung BIND_COMPLICATION_PROVIDER
hinzugefügt, damit nur das Wear OS-System eine Verbindung zu Anbieterdiensten herstellen kann.
Fügen Sie außerdem ein android:icon
-Attribut in das service
-Element ein, das ein einfarbiges weißes Symbol liefert. Wir empfehlen Vektor-Drawables für die Symbole.
Das Symbol steht für den Anbieter und wird in der Anbieterauswahl angezeigt.
Beispiel:
<service android:name=".provider.IncrementingNumberComplicationProviderService" android:icon="@drawable/icn_complications" android:label="@string/complications_provider_incrementing_number" android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER"> <intent-filter> <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST"/> </intent-filter> </service>
Metadatenelemente angeben
Füge in deiner Manifestdatei Metadaten hinzu, um die unterstützten Typen, den Aktualisierungszeitraum und die Konfigurationsaktion anzugeben, wie im folgenden Beispiel gezeigt:
<meta-data android:name="android.support.wearable.complications.SUPPORTED_TYPES" android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" /> <meta-data android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS" android:value="300" />
Wenn der Datenanbieter für die Zusatzfunktionen aktiv ist, gibt UPDATE_PERIOD_SECONDS
an, wie oft das System nach Aktualisierungen der Daten suchen soll. Wenn die in der Zusatzfunktion angezeigten Informationen nicht regelmäßig aktualisiert werden müssen, z. B. wenn Sie Push-Updates verwenden, legen Sie diesen Wert auf 0
fest.
Wenn du UPDATE_PERIOD_SECONDS
nicht auf 0
setzt, musst du einen Wert von mindestens 300
(5 Minuten) verwenden. Dies ist der minimale Updatezeitraum, den das System erzwingt, um die Akkulaufzeit des Geräts zu verlängern. Außerdem solltest du beachten, dass Aktualisierungsanfragen seltener eingehen, wenn sich das Gerät im Inaktivmodus befindet oder nicht getragen wird.
Weitere Informationen zum Senden von Aktualisierungen findest du in den Schlüsseln für die Klasse
ComplicationProviderService
in der Wear OS API-Referenz.
Konfigurationsaktivität hinzufügen
Bei Bedarf kann ein Anbieter eine Konfigurationsaktivität enthalten, die dem Nutzer angezeigt wird, wenn er einen Datenanbieter auswählt. Wenn Sie die Konfigurationsaktivität einbeziehen möchten, fügen Sie im Manifest des Anbieterdienstes ein Metadatenelement mit dem folgenden Schlüssel in die Deklaration des Anbieterdienstes ein:
<meta-data android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION" android:value="PROVIDER_CONFIG_ACTION"/>
Der Wert kann eine beliebige Aktion sein.
Erstellen Sie dann die Konfigurationsaktivität mit einem Intent-Filter für diese Aktion. Die Konfigurationsaktivität muss sich im selben Paket wie der Anbieter befinden. Die Konfigurationsaktivität muss RESULT_OK
oder RESULT_CANCELED
zurückgeben, um dem System mitzuteilen, ob der Anbieter festgelegt werden soll.
Vom Anbieter angegebene sichere Zifferblätter
Anbieter können bestimmte Zifferblätter als „sicher“ für den Empfang ihrer Daten festlegen. Dies wird nur verwendet, wenn ein Zifferblatt versucht, den Anbieter als Standard zu verwenden, und der Anbieter der Zifferblatt-App vertraut.
Um Zifferblätter als sicher zu deklarieren, fügt der Anbieter Metadaten mit dem Schlüssel android.support.wearable.complications.SAFE_WATCH_FACES
hinzu. Der Metadatenwert ist eine durch Kommas getrennte Liste von Komponentennamen von
WatchFaceService
, die so ausgegeben werden, als ob ComponentName.flattenToString()
aufgerufen wird, oder mit Namen von App-Paketen. In diesem Fall wird jedes Zifferblatt in der angegebenen App als sicher eingestuft. Leerzeichen in der Werteliste werden ignoriert. Beispiele:
<meta-data android:name="android.support.wearable.complications.SAFE_WATCH_FACES" android:value=" com.app.watchface/com.app.watchface.MyWatchFaceService, com.anotherapp.anotherwatchface/com.something.WatchFaceService, com.something.text"/>
Einbrennbare Bilder zur Verfügung stellen
Auf Bildschirmen, die anfällig für ein Einbrennen sind, sollten im Inaktivmodus einfarbige Farbblöcke vermieden werden. Wenn Ihre Symbole oder Bilder einfarbige Farbblöcke enthalten, stellen Sie auch eine eingebrannte Version bereit.
Wenn Sie ein Symbol mit
ComplicationData.Builder#setIcon
angeben, fügen Sie mithilfe von
ComplicationData.Builder#setBurnInProtectionIcon
eine eingebrannte sichere Version hinzu.
Wenn Sie ein Image mit
ComplicationData.Builder#setSmallImage
bereitstellen, fügen Sie mit
ComplicationData.Builder#setBurnInProtectionSmallImage
eine eingebrannte sichere Version hinzu.
Push-Updates verwenden
Anstatt im Manifest Ihrer App ein konstantes Aktualisierungsintervall ungleich null für eine Zusatzfunktion anzugeben, können Sie eine Instanz von
ComplicationDataSourceUpdateRequester
verwenden, um Updates dynamisch anzufordern.
Wenn du eine Aktualisierung der für Nutzer sichtbaren Inhalte der Zusatzfunktion anfordern möchtest, rufe requestUpdate()
auf.
Achtung:Zur Verlängerung der Akkulaufzeit des Geräts sollte requestUpdate()
von Ihrer Instanz von ComplicationDataSourceUpdateRequester
durchschnittlich nicht häufiger als alle 5 Minuten aufgerufen werden.
Dynamische Werte angeben
Ab Wear OS 4 können bei einigen Zusatzfunktionen Werte angezeigt werden, die aufgrund von Werten, die direkt für die Plattform verfügbar sind, häufiger aktualisiert werden. Wenn Sie diese Funktion in Ihren Zusatzfunktionen anbieten möchten, verwenden Sie
ComplicationData
-Felder, die dynamische Werte akzeptieren. Die Plattform wertet diese Werte häufig aus und aktualisiert sie, ohne dass der Anbieter der Zusatzfunktion ausgeführt werden muss.
Beispielfelder sind das
dynamische Wertfeld von GoalProgressComplicationData
und
DynamicComplicationText
, das in jedem
ComplicationText
-Feld verwendet werden kann. Diese dynamischen Werte basieren auf der
androidx.wear.protolayout.expression
-Bibliothek.
In bestimmten Situationen kann die Plattform keine dynamischen Werte auswerten:
- Der dynamische Wert ist manchmal nicht verfügbar : Dies passiert beispielsweise, wenn das Gerät nicht am Handgelenk liegt. In diesen Fällen verwendet die Plattform stattdessen den Wert des
Fallback-Felds zur dynamischen Wertentwertung im
Platzhalterfeld
NoDataComplicationData
. - Der dynamische Wert ist nie verfügbar : Dies geschieht auf Geräten, auf denen ein älterer Release von Wear OS 4 ausgeführt wird. In diesem Fall verwendet die Plattform ein Companion-Fallback-Feld wie
getFallbackValue()
.
Zeitabhängige Werte angeben
Für einige Zusatzfunktionen muss ein Wert angezeigt werden, der sich auf die aktuelle Zeit bezieht. Beispiele hierfür sind das aktuelle Datum, die Zeit bis zur nächsten Besprechung oder die Zeit in einer anderen Zeitzone.
Aktualisieren Sie eine Zusatzfunktion nicht jede Sekunde oder Minute, um diese Werte auf dem neuesten Stand zu halten. Geben Sie die Werte stattdessen in Bezug auf das aktuelle Datum oder die aktuelle Uhrzeit in einem zeitabhängigen Text an.
Sie können Builder in der Klasse
ComplicationText
verwenden, um diese zeitabhängigen Werte zu erstellen.
Aktualisierungsrate der Zusatzfunktionen
Komplikationen sollten möglichst schnell aktualisiert werden. Dies kann jedoch die Akkulaufzeit des Geräts beeinträchtigen. Sie können eine privilegierte Complication Request API verwenden, damit bestimmte Zusatzfunktionen häufiger aktualisiert werden. Die Verwendung dieser API muss jedoch vom Uhrenhersteller genehmigt werden. Jeder Uhrhersteller entscheidet, welche Zusatzfunktionen schneller als üblich aktualisiert werden können.