Ta strona została przetłumaczona przez Cloud Translation API.

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

1. Omówienie

Dzięki akcjom w aplikacji możesz za pomocą Asystenta Google przechodzić bezpośrednio do funkcji aplikacji i wykonywać zadania za pomocą głosu. Jako programista aplikacji na Androida wdrażasz elementy możliwości dodawania działań w aplikacji. Dzięki umiejętnościom Asystent może poinformować Asystenta, które funkcje aplikacji obsługują żądania głosowe użytkownika, i w jaki sposób mają być one realizowane.

To ćwiczenie w Codelabs zawiera podstawowe informacje o programowaniu za pomocą działań w aplikacji. Jeśli chcesz wykonać te ćwiczenia z programowania, musisz mieć już doświadczenie w tworzeniu aplikacji na Androida i intencjach na Androida. Jeśli dopiero zaczynasz korzystać z Androida, możesz rozpocząć jeden z modułów z programowania poświęconych podstawom programisty aplikacji na Androida.

Co utworzysz

W ramach tego ćwiczenia w programie dodasz 2 wbudowane intencje w akcjach w aplikacji do przykładowej aplikacji na Androida fitnessowej, co umożliwi użytkownikom uruchamianie i zatrzymywanie licznika czasu ćwiczeń za pomocą głosu.

Czego się nauczysz

Z kategorii Zdrowie i fitness dowiesz się, jak korzystać z BII, aby wdrożyć Asystenta w aplikacji na Androida. Nauczysz się też używać wtyczki Asystenta Google w Android Studio do testowania BII.

Wymagania wstępne

Zanim przejdziesz dalej, sprawdź, czy masz w swoim środowisku te narzędzia:

Terminal do uruchamiania poleceń powłoki z zainstalowanym narzędziem git.
Najnowsza wersja Android Studio.
Mieć konto Google z dostępem do [Konsoli Google Play][].
Fizyczne lub wirtualne urządzenie z Androidem z dostępem do internetu do 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

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

Gdy użytkownik prosi Asystenta o wykonanie zadania w Twojej aplikacji, Asystent dopasowuje jego zapytanie do capability akcji w aplikacji zdefiniowanej w zasobie XML shortcuts.xml Twojej aplikacji.

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

Rysunek 1. Schemat procesu pokazujący, jak Asystent przetwarza zapytanie głosowe w Akcjach w aplikacji.

Każdy element możliwości określa:

intent (intencja): intencja głosowa Działania w aplikacji, która powinna aktywować daną funkcję.
Co najmniej jedna realizacja: intencje związane z Androidem lub precyzyjne linki generowane przez Asystenta w celu uruchomienia aplikacji i spełnienia żądania głosowego użytkownika. Definicje realizacji określają, które parametry są oczekiwane w zapytaniu użytkownika oraz jak powinny być kodowane w instrukcjach uruchamiania.

Przeznaczenie

W rozumieniu języka naturalnego (NLU) intencja to grupa wyrażeń użytkownika o podobnym znaczeniu. Google ma dziesiątki „wbudowanych” uwzględniające szeroką gamę typów żądań dostępnych w ramach działań w aplikacji. Na przykład Asystent został przeszkolony do kojarzenia wyrażeń „Zamów pizzę” lub „Pokaż menu deserów” z ORDER_MENU_ITEM BII. Dzięki akcjom w aplikacji możesz wykorzystać te interfejsy BII, aby szybko rozszerzyć często używane polecenia głosowe do funkcji aplikacji.

Realizacje

Gdy żądanie użytkownika wywołuje działanie w aplikacji w shortcuts.xml, Twoja aktywność na Androidzie musi następnie wykryć i przeprowadzić przychodzące intencje Androida lub precyzyjny link oraz udostępnić użytkownikowi odpowiednie funkcje. W efekcie odczytywana jest strona sterowana głosem. Asystent wywołuje aplikację w odpowiedzi na zapytanie użytkownika.

3. Przygotowywanie środowiska programistycznego

W tym ćwiczeniu w Codelabs wykorzystywana jest przykładowa aplikacja Fitness na Androida. Ta aplikacja pozwala użytkownikom uruchamiać i zatrzymywać stoper ćwiczeń, a także przeglądać statystyki dotyczące ich treningów.

Pobieranie plików podstawowych

Aby uzyskać pliki podstawowe do tego ćwiczenia z programowania, uruchom to polecenie w celu sklonowania 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 Welcome to Android Studio (Witamy w Android Studio) kliknij Import project (Importuj projekt).
Znajdź i wybierz folder, do którego sklonowano repozytorium.

Aktualizowanie identyfikatora aplikacji na Androida

Aktualizowanie identyfikatora aplikacji jednoznacznie identyfikuje aplikację na urządzeniu testowym i unika „zduplikowanej nazwy pakietu”. występuje wtedy, gdy aplikacja została 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.

Wypróbuj aplikację na swoim urządzeniu

Przed wprowadzeniem kolejnych zmian w kodzie aplikacji warto zorientować się, jakie możliwości ma dana aplikacja. Testowanie aplikacji w środowisku programistycznym obejmuje te kroki:

Otwieram wirtualne lub fizyczne urządzenie testowe z Androidem.
Sprawdzam, czy aplikacja Asystent działa.
Wdrożenie i uruchomienie przykładowej aplikacji na urządzeniu przy użyciu Android Studio.

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

W Android Studio wybierz Uruchom > Uruchom aplikację lub kliknij Uruchom na pasku narzędzi.
Jeśli używasz urządzenia wirtualnego, w oknie Wybierz cel wdrożenia wybierz urządzenie wirtualne i kliknij OK. Zalecana wersja systemu operacyjnego to Android 8 (poziom interfejsu API 26) lub nowsza, jednak akcje można uruchamiać na urządzeniach już z Androidem 5 (poziom interfejsu API 21).
Po otwarciu aplikacji przytrzymaj przycisk ekranu głównego, aby skonfigurować Asystenta i sprawdzić, czy działa. Zaloguj się w Asystencie (chyba że masz to już za sobą).
Ponownie otwórz aplikację.

Telefon z otwartą aplikacją Fit Actions ze statystykami dotyczącymi ćwiczeń.

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

Omów krótko aplikację, aby poznać jej możliwości. Dotknięcie ikony Bieg powoduje uruchomienie timera, a dotknięcie ikony X - zatrzymuje stoper. Oto zadania, które możesz włączyć, by sterować głosem za pomocą komend aplikacji.

Instalowanie wtyczki Asystenta Google

Wtyczka Asystent Google umożliwia testowanie akcji w aplikacji na urządzeniu testowym. Aby dodać aplikację do Android Studio, wykonaj te czynności:

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

4. Dodaj funkcję Rozpocznij ćwiczenie BII

actions.intent.START_EXERCISE BII pozwala użytkownikom otworzyć aplikację i rozpocząć trening za pomocą głosu. W tym kroku wdrożysz funkcję BII, która pozwala użytkownikom prosić Asystenta o rozpoczęcie biegu w aplikacji Fitness.

Określ zdolność

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

Asystent dopasowuje zapytanie głosowe użytkownika do funkcji BII zdefiniowanej w możliwościach aplikacji.
Asystent wyodrębnia wartości z zapytania do parametrów BII. Każdy parametr jest dodawany do elementu Bundle powiązanego z wygenerowanym Intent.
Asystent uruchamia aplikację za pomocą Intent, udostępniając jej parametry pakietu.

START_EXERCISE BII obsługuje parametr exercise.name BII. Dzięki temu parametrowi użytkownicy będą mogli wybrać rodzaj ćwiczenia, które będą mogli śledzić w aplikacji.

Dodaj START_EXERCISE BII do swojej aplikacji, dodając capability do shortcuts.xml znajdującego się w katalogu przykładowego projektu app/src/main/res/xml:

<!-- 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 identyfikatorem applicationId zdefiniowanym w poprzednim kroku.

Poprzedni przykładowy plik XML:

Deklaruje możliwość działania funkcji START_EXERCISE BII.
Określa intent Androida, który Asystent generuje przy uruchamianiu aplikacji:
- Atrybuty targetPackage i targetClass określają aktywność odbierającą.
- Atrybut parameter mapuje parametr BII exercise.name na exerciseType w dodatkach Bundle otrzymanych przez aktywność.

Obsługa parametrów BII we wbudowanym zasobach reklamowych

Parametry BII odpowiadają elementom wyodrębnionym z zapytania użytkownika Asystenta. Na przykład gdy użytkownik powie „OK Google, uruchom uruchomienie w aplikacji Przykładowa aplikacja”Asystent wyodrębni słowo „uruchom” do parametru schema.org BII exercise.name. W przypadku niektórych identyfikatorów BII możesz poinstruować Asystenta, aby dopasował parametry BII do zbioru identyfikatorów oczekiwanych przez aplikację.

Aby to zrobić, powiąż elementy wbudowanych zasobów reklamowych z parametrem BII. Wbudowane zasoby reklamowe to zestaw obsługiwanych wartości parametrów BII, np. „bieganie”, „wycieczka” i „jog”, oraz powiązanych z nimi identyfikatorów skrótu, np. EXERCISE_RUN. To powiązanie zasobów reklamowych umożliwia Asystentowi przekazywanie do aktywności związanej z realizacją identyfikatora skrótu do pasujących parametrów zamiast nieprzetworzonej wartości zapytania.

Niektóre parametry BII, takie jak exercise.name, wymagają do działania wbudowanych zasobów reklamowych. Aby obsługiwać ten parametr, dodaj do shortcuts.xml te elementy zasobów reklamowych 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 poprzednim kodzie zdefiniowano 3 skróty reprezentujące wbudowane zasoby reklamowe dla obsługiwanych przez aplikację typów ćwiczeń: biegu, marszu i jazdy na rowerze. Każdy skrót jest powiązany z możliwością w ten sposób:

Atrybut android:key każdego elementu capability-binding odnosi się do tego samego elementu START_EXCERCISE BII zdefiniowanego dla danej możliwości.
Element parameter-binding każdego klawisza skrótu do parametru exercise.name BII.

Dodaj synonimy wbudowanych zasobów reklamowych

Atrybuty android:value elementu parameter-binding w poprzednich skrótach dotyczących zasobów reklamowych odwołują się do zasobu tablicowego synonimów dla każdego elementu zasobów reklamowych. Synonimy umożliwiają stosowanie odmian danego typu elementu, np. „bieganie”, „bieganie” i „sprint” , aby odwołać się do tego samego elementu shortcutId. 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>

Realizacja przychodzących intencji Androida

Intencje w Androidzie to obiekty do przesyłania wiadomości, za pomocą których Android wysyła żądania działania z innej aplikacji. Asystent wspiera zapytań głosowych przez generowanie intencji na podstawie szczegółów konfiguracji w uruchomionej funkcji. Aby zrealizować intencje funkcji START_EXERCISE, zaktualizuj klasę docelową FitMainActivity tak, aby obsługiwała intencję przychodzącą 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 poprzedniej funkcji Intent.handleIntent po wywołaniu ACTION_VIEW dane intencji akcji w aplikacji są przekazywane do funkcji handleIntent. Dostęp do parametrów BII połączonych w intencji START_EXERCISE uzyskuje się przez intent?.extras?.getString(START_EXERCISE). Pozostała część funkcji aktualizuje FitTrackingFragment, tak aby wyświetlała wybrany typ fitnessu startExercise.

Testowanie akcji w aplikacji

Podczas tworzenia akcji w aplikacji możesz użyć wtyczki Asystenta Google, aby wyświetlić podgląd akcji na urządzeniu testowym. Za pomocą wtyczki możesz też dostosować wartości parametrów intencji akcji i przetestować, jak aplikacja obsługuje różne sposoby, w jakie użytkownik może sformułować żądanie do Asystenta dotyczące Twojej aplikacji.

Aby przetestować akcję w aplikacji za pomocą wtyczki, wykonaj te czynności:

Uruchom aplikację w Android Studio, wybierając Uruchom > Uruchom aplikację lub kliknij ikonę 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. Gdy pojawi się prośba, przeczytaj i zaakceptuj zasady i warunki korzystania z akcji w aplikacji.
Wybierz intencję wbudowaną actions.intent.START_EXERCISE.
W polu ćwiczenie pozostaw domyślną wartość uruchomione.
Kliknij Uruchom działanie w aplikacji. Sprawdź, czy Asystent ma precyzyjne linki do minutnika ćwiczeń w aplikacji i czy ten minutnik rozpoczął trening typu biegowego.

Udało Ci się wdrożyć pierwsze akcje w aplikacji za pomocą narzędzia START_EXERCISE BII. Gratulacje! Następnie umożliwimy użytkownikom zatrzymywanie treningu biegowego w Twojej aplikacji.

5. Dodaj możliwość Zatrzymania ćwiczenia BII

actions.intent.STOP_EXERCISE BII umożliwia użytkownikom przerwanie sesji treningowej. Mogą na przykład zapytać „OK Google, przestań biegać w aplikacji PrzykładowaAplikacja”. Wdróż ten wskaźnik BII w aplikacji Fitness, dodając drugi capability do 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 we wbudowanym zasobach reklamowych

Ten BII obsługuje ten sam parametr exercise.name co START_EXERCISE BII, co pozwala użytkownikom określić, który aktywny trening chcą zakończyć. Aby włączyć tę funkcję, dodaj do shortcuts.xml drugi zestaw elementów skrótów do zasobów reklamowych:

<!-- 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>

Realizacja przychodzących intencji Androida

Włącz obsługę przychodzących intencji STOP_EXERCISE w Androidzie, aktualizując klasę FitMainActivity. Najpierw dodaj do funkcji handleIntent zmienną, która będzie przechowywać dane intencji STOP_EXERCISE:

// FitMainActivity.kt

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

Następnie zaktualizuj logikę warunkową funkcji handleIntent tak, 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 zaktualizowałeś funkcję handleIntent tak, aby szukała w przychodzącej intencji Androida kodu BII STOP_EXERCISE. Jeśli ją znajdzie, zatrzymuje aktywny minutnik i przywraca użytkownika na ekran główny.

Testowanie akcji w aplikacji

Przetestuj działanie w aplikacji, korzystając z wtyczki Asystenta Google, wykonując te czynności:

Uruchom aplikację w Android Studio, wybierając Uruchom > Uruchom aplikację lub kliknij ikonę Uruchom na górnym pasku narzędzi.
W aplikacji rozpocznij nowe polecenie „bieganie” ćwiczenia.
Otwórz wtyczkę w Android Studio: kliknij Narzędzia > Działania w aplikacji > Asystent Google > Narzędzie do testowania działań w aplikacji.
Kliknij Utwórz podgląd.
Wybierz intencję wbudowaną actions.intent.STOP_EXERCISE.
W polu ćwiczenie pozostaw domyślną wartość uruchomione.
Kliknij Uruchom działanie w aplikacji. Sprawdź, czy Asystent przerwie trening i powróci do ekranu głównego.

6. Dalsze kroki

Gratulacje!

Wiesz już, jak włączyć głosowo aplikację na Androida za pomocą intencji wbudowanych w Asystenta. Dzięki temu ćwiczeniu w programowaniu udało Ci się dowiedzieć:

Jak umożliwić użytkownikom szczegółowe poznanie konkretnych funkcji aplikacji za pomocą Asystenta.
Jak korzystać z wbudowanych zasobów reklamowych.
Jak przetestować BII za pomocą wtyczki Asystenta Google.

Co dalej?

Następnie możesz spróbować udoskonalić aplikację Fitness. Aby odwołać się do zakończonego projektu, zobacz główną gałąź na GitHubie.

Oto kilka sugestii, dzięki którym możesz dowiedzieć się więcej o rozszerzaniu możliwości korzystania z tej aplikacji za pomocą działań w aplikacji:

Zapoznaj się z innymi ćwiczeniami z programowania dotyczącymi działań w aplikacji.
Zapoznaj się z informacjami o intencjach wbudowanych w Akcjach w aplikacji, aby dowiedzieć się więcej o BII, które można zastosować w Asystencie.

Aby dalej korzystać z Actions on Google, zapoznaj się z tymi materiałami:

developers.google.com/assistant: oficjalna strona z dokumentacją Actions on Google.
Przykładowy indeks akcji w aplikacji: przykładowe aplikacje i kod do przeglądania możliwości w ramach tych działań.
Repozytorium Actions on Google GitHub: przykładowy kod i biblioteki.
r/GoogleAssistantDev: oficjalna społeczność na Reddicie dla deweloperów współpracujących z Asystentem Google.

Obserwuj nas na Twitterze @ActionsOnGoogle, aby być na bieżąco z najnowszymi informacjami. Aby poinformować o swoich dokonaniach, napisz na Twitterze #appactions.

Ankieta dotycząca opinii

Na koniec wypełnij tę ankietę, aby przekazać nam swoją opinię na temat tego ćwiczenia z programowania.