Rozszerzanie aplikacji na Androida na Asystenta Google za pomocą akcji w aplikacji

1. Przegląd

Dzięki akcjom w aplikacji możesz używać Asystenta Google do bezpośredniego przechodzenia do funkcji aplikacji i wykonywania zadań za pomocą głosu. Jako deweloper aplikacji na Androida możesz dodawać działania w aplikacji, implementując elementy funkcji. Funkcje umożliwiają Asystentowi rozpoznawanie funkcji aplikacji, które obsługują zapytania głosowe użytkowników, oraz określanie sposobu realizacji tych zapytań.

W tym ćwiczeniu znajdziesz podstawowe informacje o programowaniu z użyciem działań w aplikacji. Aby wykonać to ćwiczenie, musisz mieć doświadczenie w tworzeniu aplikacji na Androida i intencji Androida. Jeśli dopiero zaczynasz korzystać z Androida, możesz zacząć od jednego z samouczków dotyczących podstaw programowania aplikacji na Androida.

Co utworzysz

W tym module nauczysz się dodawać do przykładowej aplikacji fitness na Androida 2 wbudowane intencje działań w aplikacji, aby użytkownicy mogli włączać i wyłączać stoper ćwiczeń za pomocą głosu.

Czego się nauczysz

Dowiesz się, jak używać wbudowanych intencji z kategorii Zdrowie i fitness, aby rozszerzyć działanie Asystenta na aplikację na Androida. Nauczysz się też używać wtyczki Asystenta Google do Android Studio, aby testować wbudowane intencje.

Wymagania wstępne

Zanim przejdziesz dalej, upewnij się, że w środowisku masz te narzędzia:

Terminal do uruchamiania poleceń powłoki z zainstalowanym narzędziem git.
Najnowsza wersja Android Studio.
Konto Google z dostępem do [Konsoli Google Play][].
fizyczne lub wirtualne urządzenie z Androidem z dostępem do internetu i Sklepu Play;

Zanim przejdziesz dalej, upewnij się, że to samo konto Google jest zalogowane w Android Studio i w aplikacji Google na urządzeniu testowym.

2. Jak to działa

Działania w aplikacji łączą użytkowników z Asystenta Google z Twoją aplikacją na Androida. Jak to działa?

Gdy użytkownik poprosi Asystenta o wykonanie zadania za pomocą Twojej aplikacji, Asystent dopasuje jego zapytanie do akcji w aplikacji capability zdefiniowanej w pliku zasobu XML shortcuts.xml aplikacji.

Schemat blokowy pokazujący, jak Asystent Google przetwarza zapytanie głosowe dotyczące akcji w aplikacji

Rysunek 1. Schemat blokowy pokazujący, jak Asystent przetwarza zapytanie głosowe dotyczące działań w aplikacji.

Każdy element funkcji określa:

Intencja: intencja głosowa akcji w aplikacji, która powinna wywoływać funkcję.
Co najmniej 1 realizacja: intencje Androida lub precyzyjne linki generowane przez Asystenta w celu uruchomienia aplikacji i zrealizowania prośby głosowej użytkownika. Definicje realizacji określają, jakich parametrów oczekuje się od zapytania użytkownika i jak te parametry powinny być zakodowane w instrukcjach uruchamiania.

Intencje

W przypadku przetwarzania języka naturalnego (NLU) intencja to grupa fraz użytkownika o podobnym znaczeniu. Google udostępnia w ramach akcji w aplikacji dziesiątki „wbudowanych” intencji (BII) obejmujących szeroki zakres typów żądań. Asystent jest na przykład szkolony w zakresie kojarzenia fraz „Zamów pizzę” lub „Pokaż mi menu deserów” z ORDER_MENU_ITEM BII. Dzięki akcjom w aplikacji możesz wykorzystać te BII, aby szybko rozszerzyć typowe żądania głosowe o funkcje aplikacji.

Realizacje

Gdy żądanie użytkownika wywoła działanie w shortcuts.xml, Twoja aktywność na Androidzie musi wykryć i obsłużyć przychodzący zamiar Androida lub precyzyjny link i zapewnić użytkownikowi żądaną funkcjonalność. W rezultacie powstaje interfejs użytkownika sterowany głosem, w którym Asystent wywołuje Twoją aplikację w odpowiedzi na zapytanie użytkownika.

3. Przygotowywanie środowiska programistycznego

W tym module używana jest przykładowa aplikacja Fitness na Androida. Ta aplikacja umożliwia użytkownikom uruchamianie i zatrzymywanie timera ćwiczeń oraz wyświetlanie statystyk dotyczących ich rutynowych ćwiczeń.

Pobieranie plików podstawowych

Aby pobrać pliki podstawowe do tego ćwiczenia, uruchom to polecenie, aby sklonować repozytorium GitHub:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git

Po sklonowaniu repozytorium otwórz je w Android Studio:

W oknie Witamy w Android Studio kliknij Importuj projekt.
Znajdź i wybierz folder, do którego sklonowano repozytorium.

Aktualizowanie identyfikatora aplikacji na Androida

Aktualizacja identyfikatora aplikacji jednoznacznie identyfikuje aplikację na urządzeniu testowym i zapobiega wystąpieniu błędu „Zduplikowana nazwa pakietu”, jeśli aplikacja zostanie przesłana do Konsoli Play. Aby zaktualizować identyfikator aplikacji, otwórz app/build.gradle:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Zastąp „MYUNIQUENAME” w polu applicationId czymś unikalnym.

Wypróbuj aplikację na urządzeniu

Zanim wprowadzisz dalsze zmiany w kodzie aplikacji, warto sprawdzić, co potrafi przykładowa aplikacja. Testowanie aplikacji w środowisku deweloperskim obejmuje te czynności:

otwieranie wirtualnego lub fizycznego urządzenia testowego z Androidem;
Sprawdzanie, czy aplikacja Asystent działa.
Używanie Android Studio do wdrażania i uruchamiania przykładowej aplikacji na urządzeniu.

Aby przetestować aplikację, wykonaj te czynności:

W Android Studio wybierz Uruchom > Uruchom aplikację lub na pasku narzędzi kliknij Uruchom.
Jeśli używasz urządzenia wirtualnego, w oknie Wybierz miejsce docelowe wdrożenia wybierz urządzenie wirtualne i kliknij OK. Zalecana wersja systemu operacyjnego to Android 8 (API na poziomie 26) lub nowszy, chociaż działania działają na urządzeniach z Androidem 5 (API na poziomie 21) lub nowszym.
Po otwarciu aplikacji przytrzymaj przycisk ekranu głównego, aby skonfigurować Asystenta i sprawdzić, czy działa. Zaloguj się w Asystencie, jeśli jeszcze tego nie zrobisz.
Otwórz ponownie aplikację.

Telefon z otwartą aplikacją Fit Actions, w której widać statystyki ćwiczeń.

Rysunek 2. Przykładowa aplikacja Fit Actions wyświetlająca statystyki ćwiczeń.

Przejrzyj aplikację, aby zobaczyć, co potrafi. Kliknięcie ikony biegu uruchamia minutnik ćwiczeń, a kliknięcie ikony X zatrzymuje go. Są to zadania, które możesz włączyć do sterowania głosem za pomocą działań w aplikacji.

Instalowanie wtyczki Asystenta Google

Wtyczka Asystenta Google umożliwia testowanie działań w aplikacji na urządzeniu testowym. Aby dodać go do Androida Studio, wykonaj te czynności:

Kliknij Plik > Ustawienia (Android Studio > Preferencje na macOS).
W sekcji Wtyczki otwórz Marketplace i wyszukaj „Asystent Google”.
Zainstaluj narzędzie i ponownie uruchom Androida Studio.

4. Dodawanie funkcji Start Exercise BII

actions.intent.START_EXERCISE BII umożliwia użytkownikom otwieranie aplikacji i rozpoczynanie treningu za pomocą głosu. W tym kroku zaimplementujesz funkcję tego BII, która umożliwia użytkownikom proszenie Asystenta o rozpoczęcie biegu w aplikacji treningowej.

Zdefiniuj funkcję

Asystent używa capability elementów zdefiniowanych w shortcuts.xml do przetwarzania poleceń głosowych w tych krokach:

Asystent dopasowuje zapytanie głosowe użytkownika do wbudowanej intencji zdefiniowanej w możliwościach aplikacji.
Asystent wyodrębnia z zapytania wartości do parametrów BII. Każdy parametr jest dodawany do Bundle dołączonego do wygenerowanego Intent.
Asystent używa ikony Intent, aby uruchomić aplikację, i zapewnia jej dostęp do połączonych parametrów.

Interfejs BII START_EXERCISE obsługuje parametr exercise.name BII. Ten parametr umożliwia użytkownikom określanie rodzaju ćwiczeń, które mają być śledzone w aplikacji.

Dodaj START_EXERCISE BII do aplikacji, dodając ten capability do shortcuts.xml, który znajduje się w app/src/main/res/xml przykładowym katalogu projektu:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Zastąp PUT_YOUR_APPLICATION_ID_HERE unikalnym applicationId zdefiniowanym w poprzednim kroku.

Przykładowy plik XML:

Deklaruje funkcję dla interfejsu START_EXERCISE BII.
Określa intencję Androida intent, którą Asystent generuje, aby uruchomić aplikację:
- Atrybuty targetPackage i targetClass określają aktywność odbierającą.
- Atrybut parameter mapuje parametr exercise.name BII na exerciseType w Bundle dodatkach otrzymywanych przez aktywność.

Obsługa parametrów BII za pomocą spisu wbudowanych zasobów

Parametry BII to elementy wyodrębnione z zapytania użytkownika do Asystenta. Na przykład, gdy użytkownik powie „OK Google, rozpocznij bieg w aplikacji ExampleApp”, Asystent wyodrębni słowo „bieg” do parametru BII exercise.name schema.org. W przypadku niektórych wbudowanych intencji możesz poinstruować Asystenta, aby dopasowywał parametry wbudowanych intencji do zestawu identyfikatorów oczekiwanych przez Twoją aplikację.

W tym celu powiąż elementy spisu wbudowanych zasobów z parametrem BII. Spis wbudowanych zasobów to zestaw obsługiwanych wartości parametrów BII, np. „bieganie”, „piesze wędrówki” i „jogging”, oraz odpowiadające im identyfikatory skrótów, np. EXERCISE_RUN. To powiązanie zasobów reklamowych umożliwia Asystentowi przekazywanie do działania realizującego identyfikatora skrótu dla pasujących parametrów zamiast surowej wartości zapytania.

Niektóre parametry BII, np. exercise.name, wymagają do działania spisu wbudowanych zasobów. Aby obsługiwać ten parametr, dodaj do elementu shortcuts.xml te elementy asortymentu shortcut:

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

W powyższym kodzie zdefiniowano 3 skróty reprezentujące spis wbudowanych zasobów dla obsługiwanych przez aplikację typów ćwiczeń: biegania, chodzenia i jazdy na rowerze. Każdy skrót jest powiązany z funkcją w ten sposób:

Atrybut android:key każdego elementu capability-binding odnosi się do tego samego elementu START_EXCERCISE BII zdefiniowanego dla funkcji.
Element parameter-binding każdego skrótu klawiszowego odnosi się do parametru exercise.name BII.

Dodawanie synonimów do spisu wbudowanych zasobów

Atrybuty android:value elementu parameter-binding w poprzednich skrótach asortymentowych odnoszą się do zasobu tablicy synonimów dla każdego elementu asortymentu. Synonimy umożliwiają odwoływanie się do tego samego shortcutId za pomocą różnych odmian typu elementu, np. „biegać”, „trucht” i „sprint”. Dodaj do zasobu array.xml projektu te wpisy synonimów:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Realizowanie przychodzących intencji Androida

Intencje Androida to obiekty wiadomości, których Android używa do wysyłania do innych aplikacji próśb o wykonanie działania. Asystent realizuje zapytania głosowe użytkowników, generując intencję na podstawie szczegółów konfiguracji w wywołanej funkcji. Aby realizować intencje w przypadku funkcji START_EXERCISE, zaktualizuj klasę docelową FitMainActivity, aby obsługiwała przychodzące intencje i parametry BII.

Najpierw zastąp funkcję Intent.handleIntent tym kodem:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Następnie dodaj do klasy nową funkcję handleIntent z tym kodem:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

W powyższej funkcji Intent.handleIntent, gdy wywoływana jest funkcja ACTION_VIEW, dane intencji działania w aplikacji są przekazywane do funkcji handleIntent. Do parametrów BII w intencji START_EXERCISE uzyskuje się dostęp za pomocą intent?.extras?.getString(START_EXERCISE). Pozostała część funkcji aktualizuje FitTrackingFragment, aby wyświetlać wybrany startExercise typ aktywności.

Testowanie działania w aplikacji

Podczas tworzenia akcji w aplikacji używasz wtyczki Asystenta Google, aby wyświetlić podgląd działań na urządzeniu testowym. Możesz też użyć wtyczki, aby dostosować wartości parametru intencji działania i sprawdzić, jak aplikacja radzi sobie z różnymi sposobami, w jakie użytkownik może sformułować prośbę do Asystenta dotyczącą Twojej aplikacji.

Aby przetestować działanie aplikacji za pomocą wtyczki, wykonaj te czynności:

Uruchom aplikację w Android Studio, wybierając Run (Uruchom) > Run App (Uruchom aplikację) lub klikając ikonę Run (Uruchom) na górnym pasku narzędzi.
Kliknij Narzędzia > Działania w aplikacji > Asystent Google > Narzędzie do testowania działań w aplikacji.
Kliknij Utwórz podgląd. Jeśli pojawi się taka prośba, zapoznaj się z zasadami dotyczącymi akcji w aplikacji i warunkami korzystania z usługi i je zaakceptuj.
Wybierz wbudowaną intencję actions.intent.START_EXERCISE.
W polu exercise pozostaw domyślną wartość running.
Kliknij Uruchom działanie aplikacji. Sprawdź, czy Asystent otwiera w aplikacji precyzyjny link do timera ćwiczeń i czy timer rozpoczął trening biegowy.

Udało Ci się wdrożyć pierwsze akcje w aplikacji za pomocą interfejsu BII START_EXERCISE. Gratulacje! Następnie umożliwimy użytkownikom zatrzymanie trwającego treningu w aplikacji.

5. Dodawanie funkcji Stop Exercise BII

Interfejs actions.intent.STOP_EXERCISE BII umożliwia użytkownikom zatrzymanie sesji treningowej poprzez zadawanie pytań typu „OK Google, zatrzymaj mój bieg w aplikacji ExampleApp”. Zaimplementuj ten BII w aplikacji treningowej, dodając drugi element capability do elementu shortcuts.xml:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Zastąp PUT_YOUR_APPLICATION_ID_HERE unikalnym identyfikatorem applicationId.

Obsługa parametrów BII za pomocą spisu wbudowanych zasobów

Ten interfejs BII obsługuje ten sam parametr exercise.name co interfejs START_EXERCISE, dzięki czemu użytkownicy mogą określić, który aktywny trening chcą zakończyć. Aby to zrobić, dodaj drugi zestaw elementów skrótu do zasobów reklamowych w shortcuts.xml:

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Realizowanie przychodzących intencji Androida

Aby umożliwić aplikacji obsługę przychodzących intencji Androida STOP_EXERCISE, zaktualizuj klasę FitMainActivity. Najpierw dodaj zmienną do funkcji handleIntent, aby przechowywać dane intencji STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Następnie zmodyfikuj logikę warunkową funkcji handleIntent, aby obsługiwała intencje STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

W poprzednim kodzie zaktualizowano funkcję handleIntent, aby sprawdzała, czy w przychodzącym intencie Androida znajduje się STOP_EXERCISE BII. Jeśli funkcja znajdzie odpowiedź, zatrzyma aktywny minutnik i przekieruje użytkownika na ekran główny.

Testowanie działania w aplikacji

Aby przetestować działanie aplikacji za pomocą wtyczki Asystenta Google, wykonaj te czynności:

Uruchom aplikację w Android Studio, wybierając Run (Uruchom) > Run App (Uruchom aplikację) lub klikając ikonę Run (Uruchom) na górnym pasku narzędzi.
W aplikacji rozpocznij nowe ćwiczenie „bieganie”.
Otwórz wtyczkę w Android Studio: kliknij Narzędzia > Akcje w aplikacji > Asystent Google > Narzędzie do testowania akcji w aplikacji.
Kliknij Utwórz podgląd.
Wybierz wbudowaną intencję actions.intent.STOP_EXERCISE.
W polu exercise pozostaw domyślną wartość running.
Kliknij Uruchom działanie aplikacji. Sprawdź, czy Asystent zatrzymuje trening i wraca do ekranu głównego.

6. Dalsze kroki

Gratulacje!

Wiesz już, jak włączyć sterowanie głosowe w aplikacji na Androida za pomocą wbudowanych intencji Asystenta. Z tego laboratorium dowiedziałeś(-aś) się:

Jak umożliwić użytkownikom szczegółowe omówienie określonych funkcji aplikacji za pomocą Asystenta.
Instrukcje korzystania ze spisu wbudowanych zasobów.
Jak testować wbudowane intencje za pomocą wtyczki Asystenta Google.

Co dalej?

Możesz teraz wprowadzać dalsze ulepszenia aplikacji treningowej. Aby zobaczyć gotowy projekt, otwórz główną gałąź w GitHubie.

Oto kilka sugestii, które pomogą Ci dowiedzieć się więcej o rozszerzaniu tej aplikacji za pomocą akcji w aplikacji:

Zapoznaj się z naszymi pozostałymi ćwiczeniami z programowania dotyczącymi akcji w aplikacji.
Więcej informacji o akcjach w aplikacji wbudowanych intencjach znajdziesz w tym artykule, aby rozszerzyć swoje aplikacje na Asystenta.

Aby kontynuować przygodę z Actions on Google, zapoznaj się z tymi materiałami:

developers.google.com/assistant: oficjalna witryna z dokumentacją dotyczącą Actions on Google.
Przykładowy indeks akcji w aplikacji: przykładowe aplikacje i kod do poznawania możliwości akcji w aplikacji.
Repozytorium GitHub Actions on Google: przykładowy kod i biblioteki.
r/GoogleAssistantDev: oficjalna społeczność Reddit dla programistów pracujących z Asystentem Google.

Obserwuj nas na Twitterze @ActionsOnGoogle, aby być na bieżąco z najnowszymi ogłoszeniami, i publikuj tweety z hasztagiem #appactions, aby dzielić się swoimi osiągnięciami.

Ankieta dotycząca opinii

Na koniec wypełnij tę ankietę, aby podzielić się opinią na temat tego samouczka.