Google Assistant und Medien-Apps

Mit Google Assistant können Sie viele Geräte wie Google Home und Ihr Smartphone per Sprachbefehl steuern. Es verfügt über eine integrierte Fähigkeit, Medienbefehle zu verstehen („etwas von Beyoncé wiedergeben“) und unterstützt Mediensteuerelemente (z. B. Pause, Überspringen, Vorspulen, „Daumen hoch“).

Assistant kommuniziert über eine Mediensitzung mit Android-Medien-Apps. Sie kann Intents oder Dienste verwenden, um deine App und die Wiedergabe zu starten. Die besten Ergebnisse erzielen Sie, wenn Sie in Ihrer Anwendung alle auf dieser Seite beschriebenen Funktionen implementieren.

Mediensitzung verwenden

Jede Audio- und Video-App muss eine Mediensitzung implementieren, damit Assistant die Transportsteuerung nach Beginn der Wiedergabe ausführen kann.

Assistant verwendet zwar nur die in diesem Abschnitt aufgeführten Aktionen, es wird jedoch empfohlen, alle Vorbereitungs- und Wiedergabe-APIs zu implementieren, um die Kompatibilität mit anderen Anwendungen zu gewährleisten. Für alle Aktionen, die Sie nicht unterstützen, können die Callbacks für Mediensitzungen einfach einen Fehler mit ERROR_CODE_NOT_SUPPORTED zurückgeben.

Aktivieren Sie die Medien- und Transportsteuerung, indem Sie diese Flags im MediaSession-Objekt Ihrer App festlegen:

session.setFlags(
        MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or
        MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS
)

session.setFlags(MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS |
    MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS);

In der Mediensitzung Ihrer App müssen die unterstützten Aktionen deklariert und die entsprechenden Callbacks für die Mediensitzung implementiert werden. Deklarieren Sie die unterstützten Aktionen in setActions().

Das Beispielprojekt Universal Android Music Player ist ein gutes Beispiel für das Einrichten einer Mediensitzung.

Wiedergabeaktionen

Zum Starten der Wiedergabe über einen Dienst muss eine Mediensitzung diese PLAY-Aktionen und deren Callbacks umfassen:

Ihre Sitzung sollte außerdem diese PREPARE-Aktionen und ihre Callbacks implementieren:

(*) Die URI-basierten Aktionen von Google Assistant funktionieren nur bei Unternehmen, die Google URIs bereitstellen. Weitere Informationen zum Beschreiben Ihrer Medieninhalte für Google finden Sie unter Media Actions.

Durch die Implementierung der Vorbereitungs-APIs kann die Wiedergabelatenz nach einem Sprachbefehl reduziert werden. Medien-Apps, die die Wiedergabelatenz verbessern möchten, können die zusätzliche Zeit nutzen, um mit dem Caching von Inhalten und der Vorbereitung der Medienwiedergabe zu beginnen.

Suchanfragen parsen

Wenn ein Nutzer nach einem bestimmten Medienelement sucht, z. B. „Spiel Jazz auf [Name deiner App]“ oder „[Titel des Titels] anhören“, empfängt die Callback-Methode onPrepareFromSearch() oder onPlayFromSearch() einen Suchparameter und ein Extras-Bundle.

Ihre App sollte die Sprachsuche parsen und die Wiedergabe starten, indem Sie die folgenden Schritte ausführen:

1. Verwenden Sie das Extras-Bundle und den Suchabfragestring, die von der Sprachsuche zurückgegeben werden, um die Ergebnisse zu filtern.
2. Erstelle anhand dieser Ergebnisse eine Wiedergabeliste.
3. Spiel das relevanteste Medienelement aus den Ergebnissen ab.

Für die Methode onPlayFromSearch() wird ein zusätzlicher Parameter mit detaillierteren Informationen aus der Sprachsuche verwendet. Diese Extras helfen Ihnen dabei, Audioinhalte für die Wiedergabe in Ihrer App zu finden. Wenn die Suchergebnisse diese Daten nicht bereitstellen können, können Sie eine Logik implementieren, die die unbearbeitete Suchanfrage parst und die entsprechenden Tracks basierend auf der Abfrage abspielt.

Die folgenden Extras werden in Android Automotive OS und Android Auto unterstützt:

• EXTRA_MEDIA_ALBUM
• EXTRA_MEDIA_ARTIST
• EXTRA_MEDIA_GENRE
• EXTRA_MEDIA_PLAYLIST
• EXTRA_MEDIA_TITLE

Das folgende Code-Snippet zeigt, wie Sie die Methode onPlayFromSearch() in Ihrer MediaSession.Callback-Implementierung überschreiben, um die Sprachsuche zu parsen und die Wiedergabe zu starten:

override fun onPlayFromSearch(query: String?, extras: Bundle?) {
    if (query.isNullOrEmpty()) {
        // The user provided generic string e.g. 'Play music'
        // Build appropriate playlist queue
    } else {
        // Build a queue based on songs that match "query" or "extras" param
        val mediaFocus: String? = extras?.getString(MediaStore.EXTRA_MEDIA_FOCUS)
        if (mediaFocus == MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) {
            isArtistFocus = true
            artist = extras.getString(MediaStore.EXTRA_MEDIA_ARTIST)
        } else if (mediaFocus == MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) {
            isAlbumFocus = true
            album = extras.getString(MediaStore.EXTRA_MEDIA_ALBUM)
        }

        // Implement additional "extras" param filtering
    }

    // Implement your logic to retrieve the queue
    var result: String? = when {
        isArtistFocus -> artist?.also {
            searchMusicByArtist(it)
        }
        isAlbumFocus -> album?.also {
            searchMusicByAlbum(it)
        }
        else -> null
    }
    result = result ?: run {
        // No focus found, search by query for song title
        query?.also {
            searchMusicBySongTitle(it)
        }
    }

    if (result?.isNotEmpty() == true) {
        // Immediately start playing from the beginning of the search results
        // Implement your logic to start playing music
        playMusic(result)
    } else {
        // Handle no queue found. Stop playing if the app
        // is currently playing a song
    }
}

@Override
public void onPlayFromSearch(String query, Bundle extras) {
    if (TextUtils.isEmpty(query)) {
        // The user provided generic string e.g. 'Play music'
        // Build appropriate playlist queue
    } else {
        // Build a queue based on songs that match "query" or "extras" param
        String mediaFocus = extras.getString(MediaStore.EXTRA_MEDIA_FOCUS);
        if (TextUtils.equals(mediaFocus,
                MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE)) {
            isArtistFocus = true;
            artist = extras.getString(MediaStore.EXTRA_MEDIA_ARTIST);
        } else if (TextUtils.equals(mediaFocus,
                MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE)) {
            isAlbumFocus = true;
            album = extras.getString(MediaStore.EXTRA_MEDIA_ALBUM);
        }

        // Implement additional "extras" param filtering
    }

    // Implement your logic to retrieve the queue
    if (isArtistFocus) {
        result = searchMusicByArtist(artist);
    } else if (isAlbumFocus) {
        result = searchMusicByAlbum(album);
    }

    if (result == null) {
        // No focus found, search by query for song title
        result = searchMusicBySongTitle(query);
    }

    if (result != null && !result.isEmpty()) {
        // Immediately start playing from the beginning of the search results
        // Implement your logic to start playing music
        playMusic(result);
    } else {
        // Handle no queue found. Stop playing if the app
        // is currently playing a song
    }
}

Ein ausführlicheres Beispiel für das Implementieren der Sprachsuche zur Wiedergabe von Audioinhalten in deiner App findest du im Beispiel zum Universal Android Music Player.

Leere Abfragen verarbeiten

Wenn onPrepare(), onPlay(), onPrepareFromSearch() oder onPlayFromSearch() ohne Suchanfrage aufgerufen wird, sollte Ihre Medien-App das „aktuelle“ Medium wiedergeben. Wenn keine aktuellen Medien vorhanden sind, sollte die App versuchen, etwas abzuspielen, z. B. einen Titel aus der neuesten Playlist oder eine zufällige Wiedergabeliste. Der Assistent verwendet diese APIs, wenn ein Nutzer ohne zusätzliche Informationen „Musik auf [Name Ihrer App] abspielen“ fragt.

Wenn ein Nutzer „Spiel Musik auf [Name Ihrer App]“ sagt, versucht Android Automotive OS oder Android Auto, Ihre App durch Aufrufen der Methode onPlayFromSearch() zu starten und Audioinhalte abzuspielen. Da der Nutzer den Namen des Medienelements jedoch nicht erwähnt hat, empfängt die Methode onPlayFromSearch() einen leeren Abfrageparameter. In diesen Fällen sollte Ihre App mit der sofortigen Audiowiedergabe reagieren, z. B. eines Titels aus der neuesten Playlist oder einer Zufallswarteschlange.

Alte Unterstützung für Sprachbefehle deklarieren

In den meisten Fällen erhält Ihre App durch die oben beschriebenen Wiedergabeaktionen alle erforderlichen Wiedergabefunktionen. Bei einigen Systemen muss Ihre Anwendung jedoch einen Intent-Filter für die Suche enthalten. Sie sollten die Unterstützung für diesen Intent-Filter in den Manifestdateien Ihrer App deklarieren.

Füge diesen Code in die Manifestdatei für eine Telefon-App ein:

<activity>
    <intent-filter>
        <action android:name=
             "android.media.action.MEDIA_PLAY_FROM_SEARCH" />
        <category android:name=
             "android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Steuerelemente für Verkehrsmittel

Nachdem die Mediensitzung Ihrer App aktiviert wurde, kann Assistant Sprachbefehle geben, um die Wiedergabe zu steuern und Medienmetadaten zu aktualisieren. Damit dies funktioniert, muss Ihr Code die folgenden Aktionen aktivieren und die entsprechenden Callbacks implementieren:

Hinweis:

• Damit die Suchbefehle funktionieren, muss PlaybackState auf dem neuesten Stand von state, position, playback speed, and update time sein. Die App muss setPlaybackState() aufrufen, wenn sich der Status ändert.
• Die Medien-App muss außerdem die Metadaten der Mediensitzung auf dem neuesten Stand halten. Das unterstützt Fragen wie „Welcher Song wird gerade gespielt?“. Die App muss setMetadata() aufrufen, wenn sich die entsprechenden Felder wie Titel, Künstler und Name ändern.
• MediaSession.setRatingType() muss festgelegt werden, um die Art der Altersfreigabe anzugeben, die die App unterstützt, und die App muss onSetRating() implementieren. Wenn die App die Altersfreigabe nicht unterstützt, sollte der Bewertungstyp auf RATING_NONE festgelegt werden.

Die von dir unterstützten Sprachbefehle variieren wahrscheinlich je nach Inhaltstyp.

Sie müssen so viele der oben aufgeführten Aktionen unterstützen, wie Ihre Produktangebote zulassen. Sie müssen aber trotzdem elegant auf andere Aktionen reagieren. Wenn beispielsweise nur Premium-Nutzer zum vorherigen Element zurückkehren können, wird möglicherweise eine Fehlermeldung ausgegeben, wenn ein Nutzer der kostenlosen Stufe Assistant bittet, zum vorherigen Element zurückzukehren. Weitere Informationen finden Sie im Abschnitt zur Fehlerbehandlung.

Beispiele für Sprachbefehle

In der folgenden Tabelle finden Sie einige Beispielabfragen, die Sie beim Testen Ihrer Implementierung verwenden sollten:

Fehler

Assistant verarbeitet Fehler aus einer Mediensitzung und meldet sie den Nutzern. Achten Sie darauf, dass Ihre Mediensitzung den Transportstatus und den Fehlercode im zugehörigen PlaybackState korrekt aktualisiert, wie unter Mit einer Mediensitzung arbeiten beschrieben. Assistant erkennt alle von getErrorCode() zurückgegebenen Fehlercodes.

Häufig falsch verarbeitete Fälle

Hier sind einige Beispiele für Fehlerfälle, die Sie richtig handhaben sollten:

• Der Nutzer muss sich anmelden.
  • Setzen Sie den PlaybackState-Fehlercode auf ERROR_CODE_AUTHENTICATION_EXPIRED.
  • Legen Sie die PlaybackState-Fehlermeldung fest.
  • Setze den Status PlaybackState auf STATE_ERROR, falls dies für die Wiedergabe erforderlich ist. Ansonsten behält PlaybackState den unveränderten Status bei.
• Der Nutzer fordert eine nicht verfügbare Aktion an
  • Legen Sie den PlaybackState-Fehlercode entsprechend fest. Legen Sie beispielsweise PlaybackState auf ERROR_CODE_NOT_SUPPORTED fest, wenn die Aktion nicht unterstützt wird, oder auf ERROR_CODE_PREMIUM_ACCOUNT_REQUIRED, wenn die Aktion durch Anmeldung geschützt ist.
  • Legen Sie die PlaybackState-Fehlermeldung fest.
  • Behalten Sie den Rest von PlaybackState unverändert.
• Nutzer fordert Inhalte an, die in der App nicht verfügbar sind
  • Legen Sie den PlaybackState-Fehlercode entsprechend fest. Verwenden Sie beispielsweise ERROR_CODE_NOT_AVAILABLE_IN_REGION.
  • Legen Sie die PlaybackState-Fehlermeldung fest.
  • Setzen Sie den Status PlaybackSate auf STATE_ERROR, um die Wiedergabe zu unterbrechen. Andernfalls bleibt der Rest von PlaybackState unverändert.
• Der Nutzer fordert Inhalte an, für die keine genaue Übereinstimmung verfügbar ist. Beispiel: Ein Nutzer mit einer kostenlosen Stufe fragt nach Inhalten, die nur für Nutzer der Premium-Stufe verfügbar sind.
  • Wir empfehlen, keinen Fehler zurückzugeben, sondern eher etwas Ähnliches suchen, das sich auch abspielen lässt. Assistant spricht dann die relevanteste Sprachantwort, bevor die Wiedergabe beginnt.

Wiedergabe mit einer Absicht

Assistant kann eine Audio- oder Video-App starten und die Wiedergabe starten, indem er einen Intent mit einem Deeplink sendet.

Der Intent und der Deeplink können aus verschiedenen Quellen stammen:

• Wenn Assistant eine mobile App startet, kann er die Google Suche verwenden, um mit Markup versehene Inhalte abzurufen, die einer Wiedergabeaktion mit einem Link zugeordnet sind.
• Wenn Assistant eine TV-App startet, sollte diese einen TV-Suchanbieter enthalten, um URIs für Medieninhalte offenzulegen. Assistant sendet eine Anfrage an den Contentanbieter, der einen Intent mit einem URI für den Deeplink und einer optionalen Aktion zurückgeben sollte. Wenn die Abfrage eine Aktion im Intent zurückgibt, sendet Assistant diese Aktion und den URI an Ihre App zurück. Wenn der Anbieter keine Aktion angegeben hat, fügt Assistant dem Intent ACTION_VIEW hinzu.

Assistant fügt dem Intent, den er an deine App sendet, den zusätzlichen EXTRA_START_PLAYBACK mit dem Wert true hinzu. Deine App sollte die Wiedergabe starten, wenn sie einen Intent mit EXTRA_START_PLAYBACK empfängt.

Intents im aktiven Modus verarbeiten

Nutzer können Assistant bitten, etwas abzuspielen, während die App noch Inhalte aus einer früheren Anfrage wiedergibt. Das bedeutet, dass deine App neue Intents zum Starten der Wiedergabe erhalten kann, während die Wiedergabeaktivität bereits gestartet und aktiv ist.

Die Aktivitäten, die Intents mit Deeplinks unterstützen, sollten onNewIntent() überschreiben, um neue Anfragen zu verarbeiten.

Beim Starten der Wiedergabe fügt Assistant dem Intent, der an Ihre App gesendet wird, möglicherweise zusätzliche Flags hinzu. Insbesondere kann er FLAG_ACTIVITY_CLEAR_TOP, FLAG_ACTIVITY_NEW_TASK oder beides hinzufügen. Auch wenn der Code diese Flags nicht verarbeiten muss, reagiert das Android-System darauf. Dies kann sich auf das Verhalten Ihrer App auswirken, wenn eine zweite Wiedergabeanfrage mit einem neuen URI eingeht, während der vorherige URI noch wiedergegeben wird. Sie sollten testen, wie Ihre App in diesem Fall reagiert. Sie können das adb-Befehlszeilentool verwenden, um die Situation zu simulieren (die Konstante 0x14000000 ist das boolesche bitweise ODER der beiden Flags):

adb shell 'am start -a android.intent.action.VIEW --ez android.intent.extra.START_PLAYBACK true -d "<first_uri>"' -f 0x14000000
adb shell 'am start -a android.intent.action.VIEW --ez android.intent.extra.START_PLAYBACK true -d "<second_uri>"' -f 0x14000000

Wiedergabe von einem Dienst

Wenn deine App ein media browser service hat, das Verbindungen von Assistant zulässt, kann Assistant die App starten, indem er mit dem media session des Dienstes kommuniziert. Der Medienbrowser sollte niemals eine „Aktivität“ starten. Assistant startet Ihre Aktivität auf Grundlage des PendingIntent, den Sie mit setSessionActivity() definieren.

Sie müssen „MediaSession.Token“ festlegen, wenn Sie den Medienbrowserdienst initialisieren. Denke daran, die unterstützten Wiedergabeaktionen immer, auch während der Initialisierung, festzulegen. Assistant erwartet, dass die Medien-App die Wiedergabeaktionen festlegt, bevor Assistant den ersten Wiedergabebefehl sendet.

Um von einem Dienst zu starten, implementiert Assistant die APIs des Medienbrowsers. Sie führt TransportControls-Aufrufe durch, die PLAY-Aktionsrückrufe in der Mediensitzung Ihrer App auslösen.

Das folgende Diagramm zeigt die Reihenfolge der von Assistant generierten Aufrufe und die entsprechenden Callbacks für Mediensitzungen. Die Vorbereitungs-Callbacks werden nur gesendet, wenn sie von deiner App unterstützt werden. Alle Aufrufe sind asynchron. Assistant wartet nicht auf eine Antwort von Ihrer App.

Wenn ein Nutzer einen Sprachbefehl zum Abspielen gibt, antwortet Assistant mit einer kurzen Ansage. Sobald die Ansage abgeschlossen ist, führt Assistant eine PLAY-Aktion aus. Es wird nicht auf einen bestimmten Wiedergabestatus gewartet.

Wenn deine App die ACTION_PREPARE_*-Aktionen unterstützt, ruft Assistant die Aktion PREPARE auf, bevor die Ankündigung gestartet wird.

Verbindung zu MediaBrowserService herstellen

Damit du einen Dienst zum Starten deiner App verwenden kannst, muss Assistant eine Verbindung zum MediaBrowserService der App herstellen und dessen MediaSession.Token abrufen können. Verbindungsanfragen werden in der Methode onGetRoot() des Dienstes verarbeitet. Es gibt zwei Möglichkeiten, Anfragen zu bearbeiten:

• Alle Verbindungsanfragen akzeptieren
• Verbindungsanfragen nur von der Assistant App annehmen

Alle Verbindungsanfragen akzeptieren

Du musst ein BrowserRoot zurückgeben, damit Assistant Befehle an deine Mediensitzung senden kann. Am einfachsten ist es, allen MediaBrowser-Apps das Herstellen einer Verbindung zu MediaBrowserService zu gestatten. Sie müssen einen BrowserRoot ungleich null zurückgeben. Hier ist der entsprechende Code für den Universal Music Player:

override fun onGetRoot(
        clientPackageName: String,
        clientUid: Int,
        rootHints: Bundle?
): BrowserRoot? {

    // To ensure you are not allowing any arbitrary app to browse your app's contents, you
    // need to check the origin:
    if (!packageValidator.isCallerAllowed(this, clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return an empty browser root.
        // If you return null, then the media browser will not be able to connect and
        // no further calls will be made to other media browsing methods.
        Log.i(TAG, "OnGetRoot: Browsing NOT ALLOWED for unknown caller. Returning empty "
                + "browser root so all apps can use MediaController. $clientPackageName")
        return MediaBrowserServiceCompat.BrowserRoot(MEDIA_ID_EMPTY_ROOT, null)
    }

    // Return browser roots for browsing...
}

@Override
public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid,
                             Bundle rootHints) {

    // To ensure you are not allowing any arbitrary app to browse your app's contents, you
    // need to check the origin:
    if (!packageValidator.isCallerAllowed(this, clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return an empty browser root.
        // If you return null, then the media browser will not be able to connect and
        // no further calls will be made to other media browsing methods.
        LogHelper.i(TAG, "OnGetRoot: Browsing NOT ALLOWED for unknown caller. "
                + "Returning empty browser root so all apps can use MediaController."
                + clientPackageName);
        return new MediaBrowserServiceCompat.BrowserRoot(MEDIA_ID_EMPTY_ROOT, null);
    }

    // Return browser roots for browsing...
}

Assistant-App-Paket und Unterschrift akzeptieren

Sie können Assistant explizit erlauben, eine Verbindung zu Ihrem Medienbrowser herzustellen, indem Sie den Paketnamen und die Signatur überprüfen. Ihre App erhält den Paketnamen in der onGetRoot-Methode Ihres MediaBrowserService. Du musst ein BrowserRoot zurückgeben, damit Assistant Befehle an deine Mediensitzung senden kann. Das Beispiel Universal Music Player enthält eine Liste bekannter Paketnamen und Signaturen. Unten finden Sie die Paketnamen und Signaturen, die von Google Assistant verwendet werden.

<signature name="Google" package="com.google.android.googlequicksearchbox">
    <key release="false">19:75:b2:f1:71:77:bc:89:a5:df:f3:1f:9e:64:a6:ca:e2:81:a5:3d:c1:d1:d5:9b:1d:14:7f:e1:c8:2a:fa:00</key>
    <key release="true">f0:fd:6c:5b:41:0f:25:cb:25:c3:b5:33:46:c8:97:2f:ae:30:f8:ee:74:11:df:91:04:80:ad:6b:2d:60:db:83</key>
</signature>

<signature name="Google Assistant on Android Automotive OS" package="com.google.android.carassistant">
    <key release="false">17:E2:81:11:06:2F:97:A8:60:79:7A:83:70:5B:F8:2C:7C:C0:29:35:56:6D:46:22:BC:4E:CF:EE:1B:EB:F8:15</key>
    <key release="true">74:B6:FB:F7:10:E8:D9:0D:44:D3:40:12:58:89:B4:23:06:A6:2C:43:79:D0:E5:A6:62:20:E3:A6:8A:BF:90:E2</key>
</signature>