Utwórz shortcuts.xml

Po zidentyfikowaniu funkcji w aplikacji i odpowiedniego wbudowanego zamiaru (BII) do zaimplementowania zadeklaruj BII, które obsługuje Twoja funkcja, definiując element capability w pliku zasobu shortcuts.xml. Zadeklarowanie BII jako capability rejestruje w aplikacji obsługę tej semantycznej intencji i umożliwia realizację zapytań głosowych za pomocą Asystenta Google.

Asystent używa przetwarzania języka naturalnego do wyodrębniania parametrów z zapytania użytkownika. Referencje do wbudowanych intencji zawierają listę pól, które każdy z tych interfejsów może wyodrębnić z powiązanego zapytania użytkownika. Jeśli na przykład użytkownik wywoła funkcję [actions.intent.GET_FOOD_OBSERVATION][] w aplikacji, mówiąc „OK Google, zapytaj Aplikację X, co jadłem na obiad w ostatni piątek”, Asystent wyodrębnia z prośby użytkownika te parametry BII:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Asystent przekazuje parametry BII do usługi intent zdefiniowanej w capability. Aby uwzględnić różne sposoby wywołania interfejsu BII przez użytkownika, w ramach danej zdolności można zdefiniować co najmniej 1 element intent. Możesz na przykład zdefiniować realizację intent, która wymaga obu parametrów BII w wymienionym powyżej przykładzie. Następnie możesz zdefiniować drugi zamiar, który wymaga jednego parametru BII, foodObservation.forMeal, który podaje informacje o wszystkich posiłkach w określonym dniu, np. „OK Google, poproś Aplikację X, aby dowiedzieć się, co jadłem na obiad”.

Omówienie

Konfigurowanie działań aplikacji odbywa się za pomocą pliku shortcuts.xml umieszczonego w katalogu res/xml projektu aplikacji, a potem tworzenia odwołania do pliku shortcuts.xml w pliku manifestu aplikacji. Dodaj odwołanie do shortcuts.xml w pliku manifestu aplikacji, wykonując te czynności:

1. W pliku manifestu aplikacji (AndroidManifest.xml) znajdź aktywność, której filtry intencji mają ustawione działanie android.intent.action.MAIN i kategorię android.intent.category.LAUNCHER.

2. Dodaj odwołanie do shortcuts.xml w AndroidManifest.xml, używając tagu <meta-data> w Activity, który ma filtry intencji zarówno dla MAIN, jak i LAUNCHER, w ten sposób:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

W tym przykładzie deklarowany jest zasób XML dla pliku xml/shortcuts.xml w pliku APK. Więcej informacji o konfigurowaniu skrótów znajdziesz w dokumentacji dla programistów Androida Tworzenie skrótów statycznych.

Aby uniknąć błędów kompilacji podczas definiowania funkcji działań aplikacji w shortcuts.xml, w projekcie na Androida musi być uwzględniona biblioteka Jetpacka androidx.core:core:1.6.0 (lub nowsza wersja). Więcej informacji znajdziesz w artykule Pierwsze kroki z Android Jetpack.

Skróty statyczne

Podczas definiowania capability możesz zadeklarować statyczne elementy shortcut w shortcuts.xml, aby rozszerzyć funkcjonalność tej możliwości. Skróty statyczne są przetwarzane przez Asystenta, gdy prześlesz wersję do Konsoli Google Play. Skróty statyczne można tworzyć i aktualizować tylko przez tworzenie nowych wersji, dlatego są one najbardziej przydatne do wyróżniania typowych działań i treści w aplikacji.

Za pomocą skrótów statycznych możesz włączyć te funkcje działań w aplikacji:

• Skróty do funkcji. Utwórz skróty, które uruchamiają instancję capability z wstępnie zdefiniowanymi wartościami parametru intent. Możesz na przykład zadeklarować skrót aplikacji „Rozpocznij bieg”, który wywołuje funkcję BII START_EXERCISE w aplikacji fitness.

  Te skróty zawierają atrybuty intent, shortLabel i longLabel, dzięki czemu mogą być sugerowane i wypełniane jako elementy na proaktywnych powierzchniach, takich jak Asystent lub przy długim naciśnięciu ikony aplikacji w wyszukiwarce na Androida. Skrót działania może też pełnić funkcję skrótu elementu, o czym piszemy poniżej. Aby tak się stało, musisz powiązać capability za pomocą tagu <capability-binding>.

• Skróty dotyczące elementów. Skróty elementów zawierają listę obsługiwanych wartości parametrów do obsługi zapytań głosowych dotyczących capability. Na przykład skrót encji z listą typów ćwiczeń („wycieczka”, „trening”, itp.) powiązany z parametrem BII exercise.name w ramach możliwości START_EXERCISE. Jeśli wypowiedź użytkownika pasuje do elementu, zamiast nieprzetworzonej wartości zapytania użytkownika do intencji przekazywany jest identyfikator shortcutId.

  Skróty Entity nie definiują atrybutów intent, shortLabel ani longLabel, dlatego nie są sugerowane na stronach aktywnych. Szczegółowe informacje znajdziesz w artykule Inline inventory for App Actions (w języku angielskim).

Schemat możliwości

Tabela poniżej opisuje schemat działań aplikacji dla elementów capability w shortcuts.xml. Jeśli dodasz tag, wszystkie jego atrybuty są wymagane, chyba że są oznaczone jako „opcjonalne”.

Opis schematu możliwości

W tej sekcji opisano elementy schematu capability.

<capability>

capability, który określa działanie aplikacji, które obsługuje Twoja aplikacja. Każdy element <capability> w pliku shortcuts.xml musi zawierać co najmniej 1 element <intent>, który obsługuje wykonanie działania.

Atrybuty:

• android:name: identyfikator działania wbudowanej intencji (np. [actions.intent.GET_FOOD_OBSERVATION][]). Listę obsługiwanych wbudowanych intencji znajdziesz w przewodniku po wbudowanych intencjach.
• app:queryPatterns: tablica tablic znaków z zapytaniami, których użytkownik może oczekiwać w ramach danego zamiaru. Ten atrybut ma zastosowanie tylko do intencji niestandardowych, ponieważ modele interakcji z użytkownikiem zawierają już modele typowych sposobów wyrażania przez użytkowników zadań, które chcą wykonać, lub informacji, których szukają.

<intent>

Element intent w Androidzie określający, jak należy zrealizować zapytanie użytkownika za pomocą funkcji w aplikacji. Deweloperzy mogą podać wiele tagów <intent> w tagu capability. Asystent próbuje spełnić zapytanie użytkownika, używając pierwszego <intent> w capability, dla którego podano wszystkie wymagane parametry.

Atrybuty:

• android:action: typ zamiaru Action. Domyślna wartość to ACTION_VIEW.
• android:targetClass: klasa modułu docelowego, np.: "com.example.exercise.ExerciseActivity"
• android:targetPackage: pakiet zawierający docelową klasę Activity, na przykład "com.example.exercise
• android:data: to pole jest zastępowane przez wartość <url-template>, jeśli ten tag jest zadeklarowany w elemencie intent.

<url-template>

Szablon do tworzenia identyfikatora URI precyzyjnego linku, który ma być otwierany na urządzeniu. Jeśli wszystkie wymagane parametry są dostępne, szablon może zostać rozszerzony o wbudowane parametry intencji. Przykłady szablonów adresów URL HTTP znajdziesz w artykule w Wikipedii o szablonach adresów URL. Format szablonu jest zgodny ze specyfikacją szablonu identyfikatora URI RFC 6570.

Oto kilka przykładów wartości szablonu URL:

Więcej informacji o konfigurowaniu szablonów adresów URL znajdziesz w artykule Szablony adresów URL w wypełnianiu.

<extra>

Określa dodatkowe dane dotyczące intent. W przypadku działań aplikacji to pole służy tylko do włączenia [wywołania aplikacji na pierwszym planie][] dla capability.

<parameter>

Mapuje parametr BII na wartości parametrów intencji. Więcej informacji znajdziesz w artykule Dane parametrów i dopasowywanie.

Atrybuty:

• android:name: nazwa parametru BII, który chcesz powiązać z tym parametrem intent. Nazwa powinna być polem na poziomie liści parametru BII (np. foodObservation.aboutFood.name).
• android:key: klucz zdefiniowany przez programistę dla wartości parametru BII. Możesz na przykład zdefiniować wartość contact_name dla parametru message.recipient.name BII.
• android:mimeType: typ MIME parametru, np. text/*. To pole jest wymagane tylko w przypadku parametrów intencji niestandardowych.
• android:required: określa, czy zapytanie użytkownika musi zawierać ten parametr, aby można było go użyć do realizacji. Jeśli parametr jest niedostępny, Asystent próbuje spełnić zapytanie użytkownika, używając następnego intent zdefiniowanego dla capability.

<shortcut-fulfillment>

Określa, że intent zdefiniowany w skrótach wbudowanego zasobu reklamowego dla określonego parametru ma być używany do realizacji. Więcej informacji znajdziesz w artykule Realizacja za pomocą skrótów intencji.

<parameter> (dla <shortcut-fulfillment>)

Opcjonalny atrybut, który mapuje pojedynczy parametr BII na skrótowe wypełnienie zasobów reklamowych wstawionych w ramach. Więcej informacji znajdziesz w artykule Realizacja za pomocą skrótów intencji.

Atrybut:

• android:name: nazwa parametru BII do powiązania z realizacją skrótu katalogu wbudowanego. Nazwa powinna być polem na poziomie liści parametru BII (np. menuItem.name).

<slice>

Umożliwia Asystentowi umieszczenie wyniku zapytania pasującego do tego capability jako wycinka Androida. Więcej informacji znajdziesz w artykule Integracja działań aplikacji z Androidem Slices.

Schemat skrótu

W tej tabeli opisano atrybuty elementów shortcut, które służą do włączania funkcji działań w aplikacji. Jeśli używasz tagu, wszystkie jego atrybuty są wymagane, chyba że są oznaczone jako „opcjonalne”.

Opis schematu skrótu

W tej sekcji opisano elementy schematu shortcut.

<shortcut>

Element <shortcut> na Androida zdefiniowany w shortcuts.xml z określonymi atrybutami, które są istotne dla działań w aplikacji. Wartości ciągu tekstowego w polach shortcutShortLabel i shortcutLongLabel odwołują się do zasobów ciągu tekstowego w pliku APK.

Atrybuty:

• android:shortcutId: identyfikator tego skrótu.
• android:shortcutShortLabel: zasób ciągu znaków reprezentujący krótkie wyrażenie skrótowe. Na przykład "@string/callDavidShort" oznacza wartość „Zadzwoń do Davida”.
• android:shortcutLongLabel: zasób ciągu znaków reprezentujący długie wyrażenie skrótu. Na przykład "@string/callDavidLong" oznacza wartość „Zadzwoń do Davida”.

<intent>

Intencje Androida powiązane z tym skrótem. Ta funkcja intent jest wykonywana, gdy użytkownik uruchamia skrót za pomocą głosu lub dotyku.

Atrybuty intencji shortcut są identyczne z atrybutami capability intent.

<capability-binding>

Powiązanie shortcut z akcjami w aplikacji capability. Dodanie tego elementu do shortcut umożliwia jego obsługę głosową za pomocą Assistant.

Atrybuty:

• android:key: atrybut android:name obiektu capability, do którego jest powiązany obiekt shortcut. Na przykład: actions.intent.START_EXERCISE.

<parameter-binding>

Opcjonalny atrybut, który wiąże shortcut z jednym parametrem akcji aplikacji capability. Jeśli w przypadku zasady shortcut zdefiniowano zasadę parameter-binding, możesz użyć skrótu, aby podać wbudowany zasób reklamowy jako parametr BII. Więcej informacji znajdziesz w artykule Inline inventory for App Actions (w języku angielskim).

Atrybuty:

• android:key: nazwa parametru BII capability, z którym chcesz powiązać ten skrót. Na przykład: exercise.name.
• android:value: wartość entity. Może to być pojedynczy element entity lub lista zasobów.

<extra>

Dane extra pakietu skrótu. sameAs to jedyne dane istotne dla elementów shortcut działań w aplikacji. Adres URL sameAs odnosi się do strony internetowej, która jednoznacznie identyfikuje daną jednostkę. Służy do określenia wartości typu enum, jeśli typ parametru intencji jest podtypem schema.org/Enumeration. Jest on wymagany w przypadku pól parametrów, których typy są podtypami typu schema.org/Enumeration (np. MealTypeBreakfast).

Atrybuty:

• android:key: obsługiwana wartość działań w aplikacji to: sameAs
• android:value: wartość adresu URL sameAs

Więcej informacji znajdziesz w artykule Dopasowywanie wartości parametrów z wyliczeniami.

Opcje realizacji intencji

W elementach intent w elementach <capability> definiujesz, jak Asystent ma reagować na polecenia głosowe użytkownika, które pasują do danej funkcji. W zależności od struktury nawigacji w aplikacji możesz skonfigurować kilka sposobów uruchamiania miejsca docelowego realizacji za pomocą elementu intent.

Dostępne są te opcje realizacji:

• Jasne intencje: uruchamianie określonego komponentu aplikacji przez zdefiniowanie atrybutów targetClass i targetPackage dla intent. Jest to zalecana metoda obsługi akcji w aplikacji.

• Precyzyjne linki: uruchamiaj miejsca docelowe w aplikacji za pomocą precyzyjnych linków na Androida, definiując tag <url-template> w elemencie intent. Ta metoda jest przydatna, jeśli nawigacja w aplikacji korzysta już z precyzyjnych linków.

• Dane o zamiarze: w atrybucie intent android:data możesz podać adres URI realizacji. To pole jest zastępowane przez dane tagu <url-template>, jeśli ten tag jest też zdefiniowany w intent.

Dane parametrów i dopasowywanie

Domyślnie Asystent wysyła parametry BII wyodrębnione z zapytania użytkownika do Twojej aplikacji jako dane extra obiektu intent na Androidzie zdefiniowanego w capability.

Możesz też zadeklarować tag <url-template> w tagu capability, który zawiera zastępniki parametrów dynamicznych. Ten szablon mapuje się do jednej z Twoich aktywności na Androidzie za pomocą adresu URL linków do aplikacji, schematu niestandardowego lub adresu URL opartego na intencjach.

Korzystanie z elementów dodatkowych dotyczących zamiarów

Ten przykład pokazuje wyraźną intencję zdefiniowaną dla usługi capability:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

W przypadku takiego zapytania jak „OK Google, rozpocznij bieganie” aplikacja otrzymuje intent, który wywołuje komponent: targetPackage, targetClass. Składnik otrzymuje dodatkowy element z key = "exercise", value = "Running".

Używanie szablonu adresu URL na potrzeby precyzyjnych linków na Androida

Jeśli Twoja aplikacja obsługuje już adresy URL połączone z aplikacją z parametrami dynamicznymi, możesz zdefiniować <url-template> w intent, aby generować precyzyjne linki na Androida na potrzeby realizacji. Ten przykład definiuje <url-template>:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

W przypadku tego przykładu, gdy użytkownik podaje polecenie „OK Google, rozpocznij bieg”, aplikacja otrzymuje wygenerowany adres URL: „myapp://start?exercise=Running”.

Aby zmapować parametr BII na pozycję w adresie URL, użyj atrybutu android:name tagu <parameter>. Ten atrybut odpowiada wartości android:key w szablonie adresu URL, którą chcesz zastąpić informacjami od użytkownika. Wartość android:key musi występować w elementach <url-template> i być ujęta w nawiasy klamrowe ({}).

Dopasowywanie wartości parametrów wyliczanych

Niektóre parametry BII podają wartości z enumeracji, na przykład obsługiwane wartości tekstowe parametru BII RECORD_FOOD_OBSERVATION. W przypadku tych parametrów Asystent dopasowuje zapytanie użytkownika („Śniadanie”) do elementu, którego wartość sameAs odpowiada adresowi URL schematu wyliczenia (https://schema.googleapis.com/MealTypeBreakfast). Aby powiązać wartości wyliczenia z obsługiwaną funkcją entity, w swoim pliku shortcut deklarujesz powiązanie sameAs. Ten przykład pokazuje powiązanie sameAs z skrótem elementu w linii:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

W powyższym przykładzie, jeśli funkcja RECORD_FOOD_OBSERVATION powoduje dopasowanie do typu posiłku „śniadanie”, wraz z wypełnieniem intent jest wysyłana następująca dodatkowa treść:

• key = "for_meal"
• value = "meal_breakfast"

Funkcje

W shortcuts.xml dostępne są te funkcje akcji w aplikacji:

Zasoby reklamowe w aplikacji w ramach działań w aplikacji

W przypadku niektórych parametrów BII możesz używać skrótów, aby kierować wyodrębnianie elementów do zbioru obsługiwanych elementów określonego w sekcji shortcuts.xml, zwanego inline inventory. Szczegółowe informacje znajdziesz w artykule Zasoby reklamowe w kodze.

Niestandardowi odbiorcy o podobnych zamiarach

Intencje niestandardowe można zadeklarować w shortcuts.xml, aby umożliwić sterowanie głosem funkcjami w aplikacji, które nie pasują do dostępnych interfejsów BI. Chociaż intencje niestandardowe są podobne pod względem funkcjonalności do definicji BII, wymagają 2 dodatkowych atrybutów w elementach shortcuts.xml:

• app:queryPatterns: zasób tablicy, który deklaruje różne wzorce zapytań dla intencji niestandardowej.

• android:mimeType: typ parametru niestandardowego zamiaru. To pole nie jest wymagane w przypadku interfejsów BI, w których typ parametru jest znany. W przypadku parametrów niestandardowych intencji musisz zadeklarować obsługiwany typ semantyczny.

Więcej informacji znajdziesz w artykule Intencje niestandardowe.