App-acties ontwerpen

Met app-acties kunnen gebruikers functionaliteit in je Android-app starten door dit aan de Google Assistent te vragen of door Android-snelkoppelingen te gebruiken die worden voorgesteld door de Assistent. Dit zijn de primaire stappen om je Android-app uit te breiden met app-acties:

1. Bepaal welke in-app functionaliteit moet worden geactiveerd en wat de bijbehorende ingebouwde intentie (BII) is.
2. Geef de uitvoeringsgegevens op voor de BII.
3. Push snelkoppelingen voor je app-actie naar de Assistent.
4. Geef een voorbeeld van je app-acties weer op een testapparaat.
5. Maak een testrelease van je app.
6. Vraag een beoordeling en implementatie van je app-acties aan.

Je kunt ook dynamische snelkoppelingen definiëren voor de Assistent, zodat de Assistent deze kan voorstellen aan je gebruikers. Maak een app-actie met een voorbeeld-app door het codelab voor app-acties te volgen.

Let op: Vanwege wettelijke beperkingen mogen apps die deelnemen aan het programma Gemaakt voor gezinnen geen app-acties hebben. Als je een app-actie indient voor beoordeling voor een app die is opgenomen in het programma Gemaakt voor gezinnen, kan deze niet worden goedgekeurd.

Vereisten

Voordat je app-acties gaat ontwikkelen, moeten jij en je app aan de volgende vereisten voldoen:

• Je moet een Google-account met toegang tot de Google Play Console hebben.
• Je app moet worden gepubliceerd in de Google Play Store, omdat app-acties alleen beschikbaar zijn voor apps die daar worden gepubliceerd. Zorg ook dat je app niet is bedoeld voor gebruik in een werkprofiel. App-acties worden namelijk niet ondersteund door Managed Google Play.
• Je hebt een fysiek of virtueel apparaat nodig om je app-acties te testen.
• Je hebt de nieuwste versie van Android Studio nodig.
• Je moet hetzelfde Google-account gebruiken om in te loggen bij Android Studio, de Google-app op je testapparaat en de Google Play Console.
• Je moet de Assistent instellen op je testapparaat en deze testen door de startknop ingedrukt te houden.

Ingebouwde intenties koppelen aan app-functionaliteit

Bepaal welke functionaliteit gebruikers in je Android-app misschien willen gebruiken met een gesproken verzoek en raadpleeg de referentie voor ingebouwde intenties om geschikte BII's voor je use cases te vinden. BII's modelleren gebruikersquery's voor taken die ze willen uitvoeren. Zoek dus naar BII's die overeenkomen met belangrijke functionaliteit en gebruikersstromen in je app.

Er zijn algemene BII's die bijna elke Android-app kan gebruiken, zoals je systeemeigen in-app zoekopdracht uitbreiden naar de Assistent met de BII actions.intent.GET_THING of gebruikers specifieke app-functies laten starten met hun stem door de BII actions.intent.OPEN_APP_FEATURE te implementeren.

Belangrijk: Als onderdeel van de Vereisten voor de implementatie van app-acties moeten apps met een zoekfunctie de BII actions.intent.GET_THING implementeren, zodat gebruikers naar content in je app kunnen zoeken met veelgebruikte spraakopdrachten, zoals Hey Google, zoek naar hardloopschoenen in de Voorbeeld-app.

Er zijn ook BII's voor branche- of categoriespecifieke use cases. Een app voor het bestellen van maaltijden kan bijvoorbeeld de BII actions.intent.ORDER_MENU_ITEM gebruiken.

Opmerking: Voor gevallen waarin er geen BII voor je app-functionaliteit is, kun je een aangepaste intentie gebruiken om je app uit te breiden met app-acties.

Zorg ervoor dat elke BII die je implementeert relevant is voor je in-app functionaliteit, om een geweldige gebruikerservaring te garanderen en mogelijke vertragingen bij het goedkeuringsproces te voorkomen.

Bij app-acties worden Android-intenties vanuit de Assistent-app gestart om gebruikers rechtstreeks naar specifieke content in je app te leiden. Je kunt intenties om een activiteit expliciet te starten, definiëren door de velden targetClass en targetPackage in te vullen. Als je app al deep link-URL's voor Android implementeert, kun je de intentie configureren om een deep link voor de uitvoering te gebruiken. Raadpleeg het gedeelte Deep links van je activiteit testen voor meer informatie.

Uitvoeringsgegevens voor ingebouwde intenties verstrekken

Bij het ontwerpen van een app-actie moet je een mogelijkheid definiëren in het resourcebestand shortcuts.xml van je Android-app, waarbij je de geselecteerde BII en de bijbehorende uitvoering specificeert. Een BII modelleert de gebruikersquery voor een taak en een uitvoeringsintentie geeft de Assistent informatie over hoe de taak moet worden uitgevoerd.

In je shortcuts.xml-bestand worden BII's weergegeven als <capability>-elementen en wordt elke uitvoering weergegeven als een <intent>-element:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="menuItem.name"
                android:key="query">
            </parameter>
        </intent>
    </capability>

Opmerking: De Jetpack-bibliotheek androidx.core:core:1.6.0 (of hoger) is vereist in je Android-project om compilatiefouten te voorkomen bij het definiëren van mogelijkheden voor app-acties in shortcuts.xml. Ga voor meer informatie naar Aan de slag met Android Jetpack.

Voor de meeste BII's extraheer je intentieparameters uit de query van de gebruiker op basis van entiteiten van schema.org. Je app gebruikt die BII-parameters dan om gebruikers naar de gewenste functionaliteit te leiden. De voorgaande code wijst bijvoorbeeld de BII-parameter menuItem.name toe aan de parameter query Androidintent.

Als je acties uitvoert met deep links, gebruik je het veld urlTemplate om de deep link te definiëren die door de Assistent wordt gegenereerd:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myfoodapp://browse{?query}" />
            <parameter android:name="menuItem.name"
                android:key="query"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

Tip: Als je app meerdere intenties biedt voor één BII, probeert de Assistent deze op te lossen in de volgorde waarin ze worden getoond in het capability-element.

Raadpleeg shortcuts.xml maken voor belangrijke informatie over het toevoegen van app-acties aan het bestand shortcuts.xml. Op die pagina vind je ook hoe je de parameterwaarden kunt verstrekken die je app verwacht.

De ingebouwde intentie GET_THING implementeren

Als je app een zoekfunctie heeft, moet je de BII actions.intent.GET_THING voor die functie implementeren. De Assistent kan gebruikers dan doorsturen naar de zoekfunctie van je app voor in-app resultaten als ze query's uitvoeren zoals Hey Google, zoek naar Voorbeeldding in Voorbeeld-app.

Implementeer in je shortcuts.xml-bestand een <capability> voor de BII actions.intent.GET_THING terwijl je een andere BII implementeert. Je kunt meerdere uitvoeringen voor GET_THING gebruiken, zolang je ten minste één uitvoering verstrekt die de gebruikersquery doorgeeft aan de zoekfunctie van je app.

Hier volgt een voorbeeld om de BII actions.intent.GET_THING toe te voegen in shortcuts.xml:

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

Haal in je zoekopdracht Activity de query op uit de extra gegevens van de intent en geef deze door aan de zoekfunctie van je app. In de vorige code wordt de query, die is doorgegeven als de sleutel query, toegewezen aan de BII-parameter "thing.name". Voer daarna een zoekopdracht uit met de query en geef de resultaten weer in de gebruikersinterface.

Optioneel: Snelkoppelingen voor je app-actie naar de Assistent pushen

Nadat je een optie voor je actie hebt gedefinieerd, kunnen gebruikers je actie starten door iets te zeggen als Hey Google, bestel een pizza in Voorbeeld-app. De Assistent kan op relevante momenten Android-snelkoppelingen voor je acties voorstellen, zodat ze je acties kunnen vinden en opnieuw kunnen afspelen. De Assistent kan zowel dynamische als statische snelkoppelingen voorstellen.

Gebruik de integratiebibliotheek van Google Shortcuts om dynamische snelkoppelingen naar de Assistent te pushen. Met deze Jetpack-bibliotheek kan de Assistent je snelkoppelingen gebruiken en op het juiste moment voorstellen aan gebruikers.

Raadpleeg Dynamische snelkoppelingen naar de Assistent pushen voor meer informatie.

Een voorbeeld van je app-acties weergeven

Gebruik tijdens de ontwikkeling en tests de Google Assistent-plug-in voor Android Studio om te testen of app-acties voor je app werken. De plug-in maakt een voorbeeld van je app-acties in de Assistent voor je Google-account. Met de testtool kun je je uitvoeringsversies testen op een fysiek testapparaat of emulator door BII's te leveren met invoerparameters die je van gebruikers verwacht.

Opmerking: Je kunt ook extra testers toevoegen voor je integratie voor app-acties, zelfs als ze niet hetzelfde Play Console-account hebben. Raadpleeg Extra testers toevoegen voor meer informatie.

Terwijl je een voorbeeld van je app-acties weergeeft, kun je met je stem query's activeren op het apparaat. Deze functionaliteit is alleen beschikbaar voor query's die worden vermeld in de BII-referentie voor app-acties. Gebruik spraaktriggers alleen voor demonstraties, niet voor reguliere tests.

Opmerking: De testtool voor app-acties ondersteunt alleen het testen van BII's in de taal en-US, tenzij voorbeeldquery's voor andere landen worden vermeld in de bijbehorende referentie voor ingebouwde intenties.

Test je app in de conceptmodus met de tools voor ontwikkelaars voor de Google Play Console voordat je de app ter beoordeling indient. Raadpleeg Een release voorbereiden en uitrollen voor meer informatie over hoe je de Google Play Console gebruikt om een concept van je app te implementeren.

Een testrelease maken

Als je er klaar voor bent om je app-acties met extra testers te testen, maak je een interne of gesloten testrelease van je app. De testers van je interne en gesloten release hebben standaard toegang tot app-acties die al zijn beoordeeld en goedgekeurd.

Als je toegang wilt geven voor het testen van alle app-acties, inclusief niet-goedgekeurde acties, vraag je je testers om deel te nemen aan de Google-groep van het Ontwikkelingsprogramma voor app-acties. Leden van deze groep hebben toegang tot alle app-acties in gesloten en interne testreleases zonder dat ze voorbeelden hoeven te maken met de testtool voor app-acties. Nadat je lid bent geworden van de groep, kan het tot 3 uur duren voordat je toegang hebt.

Opmerking: App-acties in releases van open testtracks zijn pas beschikbaar voor gebruikers nadat de acties zijn beoordeeld en goedgekeurd. Ga naar het volgende gedeelte voor meer informatie.

Beoordeling en implementatie van app-acties aanvragen

App-acties zijn pas beschikbaar voor gebruikers van je gepubliceerde apps of open testreleases nadat ze zijn beoordeeld en goedgekeurd. De beoordeling van app-acties is niet van invloed op de beoordeling en de implementatiestatus van je Android-app op Google Play. Zelfs als je app-inzending is goedgekeurd en gepubliceerd in de Play Store, kan je shortcuts.xml worden beoordeeld door Google. App-acties werken pas voor je eindgebruikers als ook die beoordeling is goedgekeurd.

Als je je app implementeert, blijven app-acties geactiveerd. Opnieuw geïmplementeerde versies worden wel beoordeeld door Google. Als de nieuwe versie niet naar behoren werkt of beleidsschendingen bevat, behoudt Google zich het recht voor om App-acties voor je app te deactiveren.

Zo dien je je app-acties in voor beoordeling:

1. Accepteer de Servicevoorwaarden van Actions on Google in de Google Play Console (Geavanceerde instellingen > Actions on Google):

   

2. Upload je app, die shortcuts.xml bevat, zoals gewoonlijk voor publicatie naar de Google Play Console.

3. Nadat je je app hebt geüpload naar de Play Console, neemt Google contact met je op via de e-mail in je Play Console-account met meer informatie over de status van de beoordeling van je app-acties. Je kunt ook contact opnemen met het supportteam voor Actions on Google-ontwikkelaars als je vragen hebt over de beoordelingsstatus van je app-acties. Verstrek in het contactformulier je app-pakket-ID en kies Beoordeling van app-actie in het selectievak Hoe kunnen we je helpen?

Opmerking: Als je app is beperkt op basis van inloggegevens, moet je met je app-inzending testgegevens verstrekken. Als je testgegevens wilt verstrekken, selecteer je je app in de Play Console, ga je naar Beleid > App-content en volg je de instructies die worden vermeld voor App-toegang.

Optioneel: Deep links voor je activiteit testen

Als je een deep link wilt gebruiken om een Activity te starten met een app-actie, moet de Activity zijn ingesteld met URL's voor deep links en een bijbehorend intentiefilter hebben in het manifest van de Android-app.

Opmerking: De deep link kan zijn gebaseerd op URL's voor app-links, URL's op basis van intentie of aangepaste schema's, zoals myapp://do.thing/param=value.

Voer de volgende adb-opdracht uit om te testen of je activiteiten toegankelijk zijn en via deep links kunnen worden geactiveerd met app-acties:

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

Bijvoorbeeld:

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

Als je activiteit niet correct wordt gestart met de opdracht adb, controleer je het volgende:

• In je app-manifestbestand bevat de activiteit android:exported=true, dus deze kan worden gestart met intenties van de Google Assistent.
• Als je URL's van app-links gebruikt, volg je alle stappen in Android App Links verwerken.

Beleid voor app-acties

App-acties moeten voldoen aan specifiek beleid om ervoor te zorgen dat de gebruikers die ze activeren de beoogde functionaliteit krijgen. Neem dit beleid door voordat je je apps indient om de beste gebruikerservaring te bieden en om vertragingen of afwijzingen van Play Store-beoordelingen te voorkomen.

• Gebruikers doorverwijzen naar door de gebruiker bedoelde content

  Ingebouwde intenties (BII's) en/of parameters van app-acties mogen gebruikers alleen doorverwijzen naar de relevante en door de gebruiker bedoelde actie. Dit kan in-app content, websitecontent of informatie in segmenten of widgets zijn, zolang de functionaliteit bedoeld was door de gebruiker.

  Implementaties van de BII ORDER_MENU_ITEM helpen gebruikers bijvoorbeeld een bestelling te starten voor het aangegeven menu-item of type keuken. De enige uitzondering op dit beleid is als de BII OPEN_APP_FEATURE gebruikers doorverwijst naar het startscherm van je app.

• Gebruikers doorverwijzen naar relevante webcontent

  Als gebruikers worden omgeleid naar de content van een webpagina, moet de website relevant zijn voor de door de gebruiker bedoelde actie en eigendom zijn van het merk.

  Het is bijvoorbeeld een schending om gebruikers die de BII GET_RESERVATION activeren, om te leiden naar google.com/travel, die niet bij het merk exampledomain.com van je app hoort. Een ander voorbeeld van een schending is als gebruikers die de BII GET_CALL_HISTORY activeren, worden doorverwezen naar exampledomain.com/payment waar van ze wordt verlangd dat ze een aankoop doen.

• Relevante BII's voor app-acties implementeren

  Geïmplementeerde BII's moeten rechtstreeks gerelateerd zijn aan de content en functionaliteit van de app.

  Als je app bijvoorbeeld in de Play Store-categorie Communicatie valt, moet je de BII ORDER_MENU_ITEM niet implementeren. Deze wordt aanbevolen voor apps in de categorie Eten en drinken.

• Relevante aangepaste intenties implementeren

  Gedefinieerde query's voor aangepaste intenties hebben betrekking op de content en functionaliteit van de app. Een voorbeeld van een mogelijke schending van dit beleid is het maken van de intentie custom.action.intent.GET_RECIPE met het bijbehorende querypatroon 'Toon burrito recepten' voor een app in de Play Store-categorie Transport.

---