Google Assistant und Medien-Apps

Mit Google Assistant können Sie viele Geräte wie Google Home-Geräte oder Ihr Smartphone per Sprachbefehl steuern. Es kann Medienbefehle verstehen („Spiel etwas von Beyoncé“) und unterstützt Mediensteuerungen wie „Pausieren“, „Überspringen“, „Vorspulen“ und „Mag ich“.

Assistant kommuniziert mit Android-Media-Apps über eine Mediensitzung. Sie kann Intents oder Dienste verwenden, um Ihre App zu starten und die Wiedergabe zu starten. Für optimale Ergebnisse sollte Ihre App alle auf dieser Seite beschriebenen Funktionen implementieren.

Mediensitzung verwenden

Jede Audio- und Video-App muss eine Mediensitzung implementieren, damit der Assistant die Transportsteuerung bedienen kann, sobald die Wiedergabe gestartet wurde.

Der Assistant verwendet zwar nur die in diesem Abschnitt aufgeführten Aktionen, es empfiehlt sich jedoch, alle Vorbereitungs- und Wiedergabe-APIs zu implementieren, um die Kompatibilität mit anderen Anwendungen zu gewährleisten. Bei Aktionen, die du nicht unterstützt, können die Media-Sitzungs-Callbacks einfach einen Fehler mit ERROR_CODE_NOT_SUPPORTED zurückgeben.

Aktiviere die Medien- und Transportsteuerung, indem du die folgenden Flags im MediaSession-Objekt deiner App festlegst:

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 Mediensitzungs-Callbacks implementiert werden. Deklarieren Sie die unterstützten Aktionen in setActions().

Das Beispielprojekt Universal Android Music Player ist ein gutes Beispiel dafür, wie eine Mediensitzung eingerichtet wird.

Wiedergabeaktionen

Damit die Wiedergabe über einen Dienst gestartet werden kann, muss eine Media Session die folgenden PLAY-Aktionen und ihre Callbacks haben:

In Ihrer Sitzung sollten auch die folgenden PREPARE-Aktionen und ihre Rückrufe implementiert werden:

(*) URI-basierte Google Assistant-Aktionen funktionieren nur für Unternehmen, die Google URIs zur Verfügung stellen. Weitere Informationen zum Beschreiben Ihrer Media-Inhalte für Google finden Sie unter Media Actions.

Durch die Implementierung der Vorbereitungs-APIs kann die Wiedergabelatenz nach einem Sprachbefehl reduziert werden. Media-Apps, die die Wiedergabelatenz verbessern möchten, können die zusätzliche Zeit nutzen, um Inhalte zu cachen und die Medienwiedergabe vorzubereiten.

Suchanfragen analysieren

Wenn ein Nutzer nach einem bestimmten Media-Element sucht, z. B. „Play jazz on [your app name]“ (Spiel Jazz auf [Name deiner App]) oder „Listen to [song title]“ (Höre [Titel des Songs]), empfängt die Callback-Methode onPrepareFromSearch() oder onPlayFromSearch() einen Abfrageparameter und ein Extras-Bundle.

Ihre App sollte die Sprachsuchanfrage parsen und die Wiedergabe mit den folgenden Schritten starten:

1. Verwenden Sie das vom Sprachsuchvorgang zurückgegebene Extras-Bundle und den Suchanfragestring, um die Ergebnisse zu filtern.
2. Erstelle anhand dieser Ergebnisse eine Wiedergabeliste.
3. Das relevanteste Media-Element aus den Ergebnissen abspielen

Die Methode onPlayFromSearch() verwendet einen „Extras“-Parameter mit detaillierteren Informationen aus der Sprachsuche. Diese Extras helfen Ihnen, die Audioinhalte in Ihrer App zur Wiedergabe zu finden. Wenn die Suchergebnisse diese Daten nicht liefern können, kannst du eine Logik implementieren, um die Rohsuchanfrage zu parsen und die entsprechenden Titel basierend auf der Anfrage abzuspielen.

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 Sprachsuchanfrage 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 detaillierteres Beispiel für die Implementierung der Sprachsuche zur Wiedergabe von Audioinhalten in Ihrer App finden Sie im Universal Android Music Player-Beispiel.

Leere Anfragen verarbeiten

Wenn onPrepare(), onPlay(), onPrepareFromSearch() oder onPlayFromSearch() ohne Suchanfrage aufgerufen werden, sollte in deiner Media-App das „aktuelle“ Medium wiedergegeben werden. Wenn keine aktuellen Medien vorhanden sind, sollte die App versuchen, etwas abzuspielen, z. B. einen Titel aus der letzten Playlist oder eine zufällige Warteschlange. Der Assistent verwendet diese APIs, wenn ein Nutzer ohne zusätzliche Informationen „Play music on [your app name]“ (Spiel Musik auf [Name deiner App]) sagt.

Wenn ein Nutzer „Play music on [your app name]“ sagt, versucht Android Automotive OS oder Android Auto, Ihre App zu starten und Audio wiederzugeben, indem die onPlayFromSearch()-Methode Ihrer App aufgerufen wird. Da der Nutzer den Namen des Medienelements jedoch nicht genannt hat, empfängt die Methode onPlayFromSearch() einen leeren Suchparameter. In diesen Fällen sollte Ihre App sofort Audio wiedergeben, z. B. einen Song aus der letzten Playlist oder einer zufälligen Warteschlange.

Unterstützung für alte Sprachbefehle deklarieren

In den meisten Fällen erhält Ihre App durch die Verarbeitung der oben beschriebenen Wiedergabeaktionen alle erforderlichen Wiedergabefunktionen. Bei einigen Systemen muss Ihre App 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ügen Sie diesen Code in die Manifestdatei für eine Smartphone-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 die Wiedergabe

Sobald die Mediensitzung Ihrer App aktiv ist, kann Assistant Sprachbefehle ausgeben, um die Wiedergabe zu steuern und die Medienmetadaten zu aktualisieren. Damit das funktioniert, muss Ihr Code die folgenden Aktionen ermöglichen und die entsprechenden Callbacks implementieren:

Hinweis:

• Damit 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 Media-App muss außerdem die Metadaten der Mediensitzung auf dem neuesten Stand halten. So können Sie Fragen wie „Welcher Song läuft gerade?“ stellen. Die App muss setMetadata() aufrufen, wenn sich die entsprechenden Felder (z. B. Titel, Künstler und Name des Tracks) ändern.
• MediaSession.setRatingType() muss festgelegt werden, um den Typ der Bewertung anzugeben, die von der App unterstützt wird, und die App muss onSetRating() implementieren. Wenn die App keine Bewertungen unterstützt, sollte der Bewertungstyp auf RATING_NONE festgelegt werden.

Die von Ihnen unterstützten Sprachaktionen variieren wahrscheinlich je nach Inhaltstyp.

Sie müssen so viele der oben aufgeführten Aktionen unterstützen, wie es Ihre Produktangebote zulassen, aber trotzdem angemessen auf alle anderen Aktionen reagieren. Wenn beispielsweise nur Premium-Nutzer zum vorherigen Element zurückkehren können, können Sie einen Fehler auslösen, wenn ein Nutzer mit einem kostenlosen Konto den Assistant bittet, zum vorherigen Element zurückzukehren. Weitere Informationen finden Sie im Abschnitt zur Fehlerbehandlung.

Beispiele für Sprachabfragen zum Ausprobieren

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

Fehler

Der Assistant verarbeitet Fehler aus einer Mediensitzung, wenn sie auftreten, und meldet sie den Nutzern. Achte darauf, dass in deiner Mediensitzung der Transportstatus und der Fehlercode in der PlaybackState korrekt aktualisiert werden, wie unter Mit einer Mediensitzung arbeiten beschrieben. Der Assistant erkennt alle Fehlercodes, die von getErrorCode() zurückgegeben werden.

Häufig falsch behandelte Fälle

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

• Nutzer muss sich anmelden
  • Legen Sie den PlaybackState-Fehlercode auf ERROR_CODE_AUTHENTICATION_EXPIRED fest.
  • Legen Sie die Fehlermeldung PlaybackState fest.
  • Wenn für die Wiedergabe erforderlich, setzen Sie den PlaybackState-Status auf STATE_ERROR. Andernfalls behalten Sie den Rest von PlaybackState bei.
• Nutzer fordert eine nicht verfügbare Aktion an
  • Legen Sie den Fehlercode PlaybackState entsprechend fest. Setzen Sie beispielsweise PlaybackState auf ERROR_CODE_NOT_SUPPORTED, wenn die Aktion nicht unterstützt wird, oder auf ERROR_CODE_PREMIUM_ACCOUNT_REQUIRED, wenn die Aktion durch die Anmeldung geschützt ist.
  • Legen Sie die Fehlermeldung PlaybackState fest.
  • Behalten Sie den Rest von PlaybackState unverändert bei.
• Nutzer fordern Inhalte an, die in der App nicht verfügbar sind
  • Legen Sie den Fehlercode PlaybackState entsprechend fest. Verwenden Sie beispielsweise ERROR_CODE_NOT_AVAILABLE_IN_REGION.
  • Legen Sie die Fehlermeldung PlaybackState fest.
  • Setze den PlaybackSate-Status auf STATE_ERROR, um die Wiedergabe zu unterbrechen. Behalte ansonsten den Rest von PlaybackState bei.
• Nutzer fordern Inhalte an, für die keine genaue Übereinstimmung verfügbar ist. Ein Nutzer mit kostenlosem Abo fragt beispielsweise nach Inhalten, die nur für Nutzer mit Premium-Abo verfügbar sind.
  • Wir empfehlen, keinen Fehler zurückzugeben, sondern stattdessen nach etwas Ähnlichem zu suchen, das abgespielt werden kann. Der Assistant spricht die relevanteste Sprachantwort, bevor die Wiedergabe beginnt.

Wiedergabe mit Intention

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

Die Intention und der zugehörige Deeplink können aus verschiedenen Quellen stammen:

• Wenn Assistant eine mobile App startet, kann er über die Google Suche markierte Inhalte abrufen, die eine Wiedergabeaktion mit einem Link enthalten.
• Wenn Assistant eine TV-App startet, sollte Ihre App einen TV Search Provider enthalten, um URIs für Medieninhalte bereitzustellen. Der Assistant sendet eine Anfrage an den Contentanbieter, der eine Absicht mit einem URI für den Deeplink und einer optionalen Aktion zurückgeben sollte. Wenn die Anfrage eine Aktion im Intent zurückgibt, sendet Assistant diese Aktion und den URI zurück an Ihre App. Wenn der Anbieter keine Aktion angegeben hat, fügt Assistant ACTION_VIEW zum Intent hinzu.

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

Umgang mit Intents während der Aktivität

Nutzer können Google Assistant bitten, etwas abzuspielen, während in Ihrer App noch Inhalte aus einer vorherigen Anfrage wiedergegeben werden. Das bedeutet, dass deine App neue Intents zum Starten der Wiedergabe empfangen 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, das an Ihre App gesendet wird, möglicherweise zusätzliche Flags hinzu, insbesondere FLAG_ACTIVITY_CLEAR_TOP oder FLAG_ACTIVITY_NEW_TASK oder beides. Ihr Code muss diese Flags zwar nicht verarbeiten, das Android-System reagiert jedoch 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. Es empfiehlt sich, zu testen, wie Ihre App in diesem Fall reagiert. Mit dem adb-Befehlszeilentool können Sie die Situation 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 über einen Dienst

Wenn Ihre App eine media browser service hat, die Verbindungen von Assistant zulässt, kann Assistant die App starten, indem er mit der media session des Dienstes kommuniziert. Der Medienbrowser-Dienst sollte niemals eine Aktivität starten. Der Assistent startet Ihre Aktivität basierend auf dem PendingIntent, das Sie mit setSessionActivity() definieren.

Achte darauf, das MediaSession.Token festzulegen, wenn du den Media-Browser-Dienst initialisierst. Denken Sie daran, die unterstützten Wiedergabeaktionen jederzeit festzulegen, auch während der Initialisierung. Der Assistant erwartet, dass deine Media-App die Wiedergabeaktionen festlegt, bevor der Assistant den ersten Wiedergabebefehl sendet.

Wenn Sie von einem Dienst aus starten, implementiert der Assistant die Media Browser Client APIs. Es werden TransportControls-Aufrufe ausgeführt, die PLAY-Aktions-Callbacks in der Mediensitzung Ihrer App auslösen.

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

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

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

Verbindung zu einem MediaBrowserService herstellen

Damit ein Dienst Ihre App starten kann, muss Assistant eine Verbindung zum MediaBrowserService der App herstellen und das MediaSession.Token abrufen können. Verbindungsanfragen werden in der onGetRoot()-Methode des Dienstes verarbeitet. Es gibt zwei Möglichkeiten, Anfragen zu bearbeiten:

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

Alle Verbindungsanfragen annehmen

Sie müssen einen BrowserRoot zurückgeben, damit der Assistant Befehle an Ihre Mediensitzung senden kann. Am einfachsten ist es, allen MediaBrowser-Apps die Verbindung zu Ihrem MediaBrowserService zu erlauben. Sie müssen einen BrowserRoot zurückgeben, der nicht null ist. Hier ist der entsprechende Code aus dem 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 ‑Signatur akzeptieren

Sie können Google Assistant explizit erlauben, eine Verbindung zu Ihrem Media Browser-Dienst herzustellen, indem Sie den Paketnamen und die Signatur prüfen. Ihre App erhält den Paketnamen in der Methode „onGetRoot“ Ihres MediaBrowserService. Sie müssen einen BrowserRoot zurückgeben, damit der Assistant Befehle an Ihre Mediensitzung senden kann. Im Beispiel Universal Music Player wird eine Liste bekannter Paketnamen und Signaturen verwaltet. 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>