Daten für Zusatzfunktionen bereitstellen

Datenanbieter-Apps machen Informationen auf dem Zifferblatt sichtbar Zusatzfunktionen, Felder mit Text, Zeichenfolgen, Bildern und Zahlen angeben.

Ein Datenanbieterdienst erweitert <ph type="x-smartling-placeholder"></ph> ComplicationProviderService, um nützliche direkt auf dem Zifferblatt.

Datenanbieterprojekt erstellen

So erstellen Sie ein für Ihre Datenanbieter-App zu erstellen, führen Sie die folgenden Schritte aus:

  1. Klicken Sie auf Datei > Neu > Neues Projekt.
  2. Klicke im Fenster Project Template (Projektvorlage) auf den Tab „Wear OS“ und wähle Keine Aktivität und klicken Sie auf Weiter.
  3. Geben Sie im Fenster Projekt konfigurieren einen Namen für Ihr Projekt ein, füllen Sie Standard-Projektinformationen ein und klicken Sie auf Finish (Fertigstellen).
  4. Android Studio erstellt ein Projekt mit einem App-Modul für Ihren Datenanbieter. Weitere Informationen Informationen zu Projekten in Android Studio finden Sie unter Projekt erstellen
  5. Erstellen Sie eine neue Klasse, die Ihre Datenanbieter-App erweitert, <ph type="x-smartling-placeholder"></ph> BroadcastReceiver Der Zweck dieser Klasse besteht darin, Updateanfragen für Zusatzfunktionen vom Wear OS-System gesendet werden. Erstellen Sie außerdem ein neue Klasse, die Ihre <ph type="x-smartling-placeholder"></ph> ComplicationProviderService, um Daten bereitzustellen die von entsprechenden Komplikationen angefordert werden. Weitere Informationen finden Sie hier: <ph type="x-smartling-placeholder">

    Hinweis:Das Hinzufügen einer Aktivität für Ihren Datenanbieter optional. Angenommen, Sie möchten eine Aktivität, die nur gestartet wird, wenn die Nutzenden auf eine Komplikationen.

Methode für Aktualisierungsanfragen implementieren

Wenn Daten zu Zusatzfunktionen benötigt werden, sendet das Wear OS-System Aktualisierungsanfragen an deine Daten Dienstanbieter. Die Anfragen gehen an Ihr <ph type="x-smartling-placeholder"></ph> BroadcastReceiver Um auf Aktualisierungsanfragen zu reagieren, muss Ihr Datenanbieter die <ph type="x-smartling-placeholder"></ph> Methode onComplicationUpdate() des ComplicationProviderService .

Das Wear OS-System ruft onComplicationUpdate() auf, wenn es Daten von deinem z. B. wenn bei der Nutzung Ihres Anbieters aktiv sind oder eine festgelegte Zeitspanne verstreichen. Sie übergibt eine ComplicationManager-Objekt als Parameter für onComplicationUpdate, mit dem Daten zurück an das System gesendet werden.

Hinweis:Wenn Ihre Datenanbieter-App Daten bereitstellt, zeigt das Zifferblatt die von Ihnen gesendeten Rohwerte, sodass es die Informationen abrufen kann.

Das folgende Code-Snippet zeigt eine Beispielimplementierung des onComplicationUpdate-Methode:

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

Apps von Datenanbietern müssen bestimmte Deklarationen im App-Manifest enthalten, damit sie als Datenanbieter durch das Android-System. In diesem Abschnitt werden die erforderlichen Einstellungen für Datenanbieter-Apps.

Deklarieren Sie im Manifest Ihrer App den Dienst und fügen Sie einen Intent-Filter für Aktualisierungsanfragen hinzu. Außerdem muss das Manifest den Dienst durch Hinzufügen des BIND_COMPLICATION_PROVIDER-Objekts schützen. Berechtigung, um sicherzustellen, dass sich nur das Wear OS-System an Anbieterdienste binden kann.

Fügen Sie außerdem ein android:icon-Attribut in den service-Element, das ein einfarbiges weißes Symbol. Wir empfehlen Vektor-Drawables für die Symbole. Das Symbol repräsentiert den Anbieter und wird im Anbieter angezeigt -Auswahl.

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 deiner Manifestdatei Metadaten hinzu, um die unterstützten Typen anzugeben. Aktualisierungszeitraum und Konfigurationsaktion, wie unten dargestellt Beispiel: 

<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 Ihr Datenanbieter für Zusatzfunktionen aktiv ist, UPDATE_PERIOD_SECONDS gibt an, wie oft das Ereignis um nach Aktualisierungen der Daten zu suchen. Wenn die Informationen in der Zusatzfunktion nicht regelmäßig aktualisiert werden, Push-Updates verwenden, setzen Sie diesen Wert auf 0

Wenn Sie UPDATE_PERIOD_SECONDS nicht auf 0 festlegen, Sie müssen einen Wert von mindestens 300 (5 Minuten) verwenden, die vom System erzwungene Mindestaktualisierungsdauer, um die Akkulaufzeit des Geräts. Beachten Sie außerdem, dass Aktualisierungsanfragen erscheinen seltener, wenn sich das Gerät im Inaktivmodus befindet oder nicht getragen wird.

Weitere Informationen zum Senden von Updates finden Sie in den Schlüsseln für die <ph type="x-smartling-placeholder"></ph> ComplicationProviderService in der Wear OS API Referenz.

Konfigurationsaktivität hinzufügen

Bei Bedarf kann ein Anbieter eine Konfigurationsaktivität hinzufügen, die dem Nutzer angezeigt werden, wenn er einen Datenanbieter auswählt. Um den Parameter Konfigurationsaktivität, fügen Sie ein Metadatenelement in den Providerdienst ein -Deklaration im Manifest mit dem folgenden Schlüssel an: 

<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 dafür. Aktion ausführen. Die Konfigurationsaktivität muss sich im selben Paket befinden wie die Dienstanbieter. Die Konfigurationsaktivität muss RESULT_OK oder RESULT_CANCELED, um dem System mitzuteilen, festgelegt werden sollte.

Vom Anbieter angegebene sichere Zifferblätter

Anbieter können bestimmte Zifferblätter als „sicher“ festlegen um ihre Daten. Dies wird nur verwendet, wenn ein Zifferblatt versucht, um den Anbieter als Standardeinstellung 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 Die metadata ist eine durch Kommas getrennte Liste mit entweder <ph type="x-smartling-placeholder"></ph> WatchFaceService-Komponentennamen, die so angegeben werden ComponentName.flattenToString() wird aufgerufen oder App-Paketnamen. In diesem Fall sind alle Zifferblätter innerhalb eines angegebene App als sicher gilt. Leerzeichen in der Werteliste werden ignoriert. Beispiel: 

<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"/>

Eingebrannte Bilder bereitstellen

Auf Bildschirmen, die ein Einbrennen verursachen können, sollten durchgehende Farbblöcke in Ambient-Modus zu wechseln. Wenn Ihre Symbole oder Bilder einfarbige Farbblöcke enthalten, bieten auch eine einbrennbare Version.

Wenn Sie mithilfe von <ph type="x-smartling-placeholder"></ph> ComplicationData.Builder#setIcon, enthalten eine einbrennbare Version mit <ph type="x-smartling-placeholder"></ph> ComplicationData.Builder#setBurnInProtectionIcon

Wenn Sie ein Bild mithilfe von <ph type="x-smartling-placeholder"></ph> ComplicationData.Builder#setSmallImage, enthalten eine einbrennbare Version mit <ph type="x-smartling-placeholder"></ph> ComplicationData.Builder#setBurnInProtectionSmallImage

Push-Updates verwenden

Als Alternative zur Angabe eines konstanten Aktualisierungsintervalls ungleich null für ein im Manifest Ihrer App angezeigt wird, können Sie <ph type="x-smartling-placeholder"></ph> ComplicationDataSourceUpdateRequester, um Aktualisierungen dynamisch anzufordern. Um eine Aktualisierung des für den Nutzer sichtbaren Inhalt der Zusatzfunktion anzufordern, rufen Sie requestUpdate()

Achtung:Um die Akkulaufzeit Ihres Geräts zu verlängern, ruf requestUpdate() nicht von deiner Instanz von aus auf ComplicationDataSourceUpdateRequester häufiger als alle 5 Minuten am Durchschnitt.

Dynamische Werte angeben

Ab Wear OS 4 können bei einigen Zusatzfunktionen Werte angezeigt werden, die häufiger aktualisiert werden basierend auf Werten, die direkt für die Plattform verfügbar sind. Um diese Fähigkeit in die Zusatzfunktionen nutzen, <ph type="x-smartling-placeholder"></ph> ComplicationData-Felder, die akzeptiert werden: dynamische Werte. Die Plattform wertet und evaluiert aktualisiert diese Werte häufig, ohne dass der Zusatzdienstanbieter ausgeführt werden muss.

Beispiele für Felder: <ph type="x-smartling-placeholder"></ph> das dynamische Wertfeld von GoalProgressComplicationData und <ph type="x-smartling-placeholder"></ph> DynamicComplicationText, die in jedem ComplicationText eingeben. Diese dynamischen Werte basieren auf dem <ph type="x-smartling-placeholder"></ph> androidx.wear.protolayout.expression.

In bestimmten Situationen kann die Plattform dynamische Werte nicht auswerten:

Zeitabhängige Werte angeben

Bei einigen Zusatzfunktionen muss ein Wert angezeigt werden, der sich auf den aktuellen . Beispiele hierfür sind das aktuelle Datum, die Zeit bis zum nächsten Meeting, oder die Uhrzeit in einer anderen Zeitzone.

Zusatzfunktion nicht jedes Mal aktualisieren um diese Werte auf dem neuesten Stand zu halten. Geben Sie stattdessen an, mit zeitabhängigem Text die Werte relativ zum aktuellen Datum oder zur aktuellen Uhrzeit anzeigen. Sie können Builder in der ComplicationText, um diese zeitabhängigen Werte zu erstellen.

Aktualisierungsrate der Zusatzfunktion

Möglicherweise möchten Sie Zusatzfunktionen schnell aktualisieren. Dies kann sich jedoch auf den Akku auswirken. Lebensdauer des Geräts. Sie können eine privilegierte <ph type="x-smartling-placeholder"></ph> Complication Request API, mit dem bestimmte Zusatzfunktionen häufiger aktualisiert werden können. Die Verwendung dieser API muss jedoch zulässig sind, Hersteller der Uhr. Jeder Uhrenhersteller entscheidet, welche Zusatzfunktionen aktualisiert werden können, schneller als normalerweise zulässig.