Daten für Zusatzfunktionen bereitstellen

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:

  1. Klicken Sie auf Datei > Neu > Neues Projekt.
  2. Klicken Sie im Fenster Projektvorlage auf den Tab „Wear OS“, wählen Sie Keine Aktivität aus und klicken Sie auf Weiter.
  3. Benennen Sie Ihr Projekt im Fenster Projekt konfigurieren, geben Sie die Standardprojektinformationen ein und klicken Sie auf Fertigstellen.
  4. 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.
  5. 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, die ComplicationProviderService erweitert, um Daten bereitzustellen, wenn diese durch entsprechende Zusatzfunktionen angefordert werden. Weitere Informationen finden Sie hier:

    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.