Utwórz shortcuts.xml

Po ustaleniu funkcji w aplikacji i odpowiadającej jej intencji wbudowanej (BII) do implementacji zadeklaruj identyfikatory BII obsługiwane przez daną funkcję, definiując element capability w pliku zasobów shortcuts.xml. Zadeklarowanie BII jako elementu capability rejestruje obsługę tej intencji semantycznej w aplikacji i umożliwia głosowe realizowanie intencji za pomocą Asystenta Google.

Asystent wykorzystuje przetwarzanie języka naturalnego do wyodrębniania parametrów z zapytań użytkownika. Dokumentacja intencji wbudowanych zawiera listę pól, które każdy BII może wyodrębnić z powiązanego zapytania użytkownika. Jeśli na przykład użytkownik wywoła w aplikacji funkcję actions.intent.ORDER_MENU_ITEM, mówiąc „OK Google, zamów pizzę z przykładowej kawiarni w przykładowej aplikacji”, Asystent pobierze z prośby użytkownika te parametry BII:

• menuItem.name = "pizza"
• menuItem.inMenuSection.inMenu.forRestaurant.name = "PrzykładowaKawiarnia"

Asystent przekazuje parametry BII do realizacji intent zdefiniowanej w capability. Można zdefiniować co najmniej 1 element intent w celu dostosowania do różnych sposobów wywoływania przez użytkownika BII. W przykładzie powyżej możesz zdefiniować realizację intent, która wymaga obu parametrów BII. Następnie możesz zdefiniować drugą intencję, która wymaga pojedynczego parametru BII – menuItem.name. Wyświetla ona opcje restauracji w pobliżu, jeśli użytkownik wysyła prostsze żądanie, np. „OK Google, zamów pizzę w aplikacji ExampleApp”.

.

Przegląd

Konfigurujesz akcje w aplikacji za pomocą pliku shortcuts.xml umieszczonego w katalogu res/xml projektu aplikacji, a następnie tworzysz odniesienie do shortcuts.xml w manifeście aplikacji. Dodaj odwołanie do pola shortcuts.xml w manifeście aplikacji. Aby to zrobić:

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

2. Dodaj odwołanie do funkcji shortcuts.xml w pliku AndroidManifest.xml za pomocą tagu <meta-data> w elemencie Activity, który zawiera filtry intencji zarówno dla MAIN, jak i LAUNCHER:

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

Powyższy przykład deklaruje zasób XML dla pliku xml/shortcuts.xml w pakiecie APK. Więcej informacji o konfigurowaniu skrótów znajdziesz w sekcji Tworzenie skrótów statycznych w dokumentacji dla programistów aplikacji na Androida.

Biblioteka Jetpack androidx.core:core:1.6.0 (lub nowsza) jest wymagana w projekcie Androida, aby uniknąć błędów kompilacji przy definiowaniu możliwości akcji w aplikacji w shortcuts.xml. Więcej informacji znajdziesz w artykule Pierwsze kroki z Androidem Jetpack.

Skróty statyczne

Podczas definiowania elementu capability możesz zadeklarować statyczne elementy shortcut w shortcuts.xml, aby rozszerzyć zakres funkcji. Skróty statyczne są przetwarzane przez Asystenta, gdy przesyłasz wersję do Konsoli Google Play. Skróty statyczne można tworzyć i aktualizować tylko podczas tworzenia nowych wersji, dlatego najbardziej przydają się one do wyróżniania typowych działań i treści w aplikacji.

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

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

  Te skróty zawierają atrybuty intent, shortLabel i longLabel, dzięki czemu mogą być sugerowane i wykonywane jako elementy w aktywnych miejscach, takich jak Asystent lub po przytrzymaniu ikony aplikacji w Menu z aplikacjami na Androida. Skrót do działania może też służyć jako skrót do elementu (opis znajdziesz poniżej) przez powiązanie go z elementem capability za pomocą tagu <capability-binding>.

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

  Skróty Entity nie definiują atrybutów intent, shortLabel ani longLabel, więc nie są sugerowane na platformach bez pytania. Więcej informacji znajdziesz w artykule Wbudowane zasoby reklamowe na potrzeby działań w aplikacji.

Schemat możliwości

W tabeli poniżej opisujemy schemat działań w aplikacji dla elementów capability w komponencie shortcuts.xml. Gdy dodajesz tag, wszystkie jego atrybuty są wymagane, chyba że oznaczono je jako „opcjonalne”.

Tag shorts.xml	Zawarte w	Atrybuty
<capability>	<shortcuts>	android:name app:queryPatterns (ma zastosowanie tylko w przypadku niestandardowych intencji)
<intent>	<capability>	android:action (opcjonalnie) android:targetClass (opcjonalnie) android:targetPackage (opcjonalnie) android:data (opcjonalnie)
<url-template>	<intent>	android:value
<extra>	<intent>	android:key android:value Dotyczy tylko wywołania aplikacji na pierwszym planie
<parameter>	<intent>	android:name android:key android:mimeType (ma zastosowanie tylko w przypadku niestandardowych intencji) android:required (opcjonalnie) app:shortcutMatchRequired (opcjonalnie)
<data>	<parameter>	android:pathPattern (ma zastosowanie tylko w przypadku internetowych zasobów reklamowych)
<shortcut-fulfillment>	<capability>	Problem dotyczy tylko wbudowanych zasobów reklamowych.
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	Dotyczy tylko wycinków Androida

Opis schematu możliwości

W tej sekcji opisujemy elementy schematu capability.

<capability>

Element capability definiujący intencję akcji w aplikacji obsługiwaną przez aplikację. Każdy element <capability> w pliku shortcuts.xml musi zawierać co najmniej 1 element <intent>, który umożliwia wykonanie działania.

Atrybuty:

• android:name: identyfikator akcji wbudowanej intencji (np. actions.intent.CREATE_TAXI_RESERVATION). Listę obsługiwanych intencji wbudowanych znajdziesz w dokumentacji intencji wbudowanej.
• app:queryPatterns: tablica ciągów znaków stanowiących zapytania oczekiwane od użytkownika w przypadku tej intencji. Ten atrybut ma zastosowanie tylko w przypadku intencji niestandardowych, ponieważ intencje BII zawierają już modele typowych sposobów wyrażania przez użytkowników zadań, które próbują wykonać, lub informacji, których szukają.

<zamiar>

Element Androida intent określający sposób wypełniania zapytania użytkownika za pomocą funkcji w aplikacji. Deweloperzy mogą umieścić wiele tagów <intent> w elemencie capability. Asystent próbuje zrealizować zapytanie użytkownika za pomocą pierwszych <intent> w capability, dla którego podano wszystkie wymagane parametry.

Atrybuty:

• android:action: typ Action intencji. Domyślna wartość to ACTION_VIEW.
• android:targetClass: docelowa klasa aktywności, np.: "com.example.food.OrderActivity"
• android:targetPackage: pakiet zawierający docelową klasę aktywności, np. "com.example.food"
• android:data: to pole jest zastąpione przez <url-template>, jeśli ten tag jest zadeklarowany w intent.

<szablon-url>

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

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

Szablon	Wartości	Wartość rozwinięta
https://example.com/test{?foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo}	"foo": "123"	https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo}	"foo": "123"	myapp://example/123

Więcej informacji o konfigurowaniu szablonów adresów URL znajdziesz w artykule Szablony adresów URL w realizacji.

<ekstra>

Definiuje dodatkowe dane dla elementu intent. W przypadku akcji w aplikacji to pole służy tylko do włączania wywołania aplikacji na pierwszym planie dla capability.

<parametr>

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

Atrybuty:

• android:name: nazwa parametru BII do powiązania z tym parametrem intent. Nazwa powinna być polem na poziomie liścia parametru BII (np. foodObservation.aboutFood.name).
• android:key: zdefiniowany przez dewelopera klucz wartości parametru BII. Możesz na przykład zdefiniować contact_name dla parametru message.recipient.name BII.
• android:mimeType: typ mimeType 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, by intencja mogła zostać użyta do realizacji. Jeśli parametr jest niedostępny, Asystent próbuje zrealizować zapytanie użytkownika, korzystając z następnego parametru intent zdefiniowanego w polu capability.

<dane>

Wiąże internetowe zasoby reklamowe z parameter.

Atrybut:

• android:pathPattern: wzorzec URL-a (entity) do zwrócenia w zasobach reklamowych w internecie. Ten atrybut obsługuje dwa symbole wieloznaczne:

  • *: gwiazdka odpowiada sekwencji 0 lub większej liczby wystąpień bezpośrednio poprzedzającego znaku.

  • .*: kropka, po której następuje gwiazdka, odpowiada dowolnej sekwencji zerowej lub większej liczby znaków.

  • Znaki Escape różnią się tylko w przypadku literału * i \, które można zmienić odpowiednio jako \\* i \\\\.

<shortcut-fulfillment>

Określa, że do realizacji jest używany skrót intent określony we skrócie do zasobu wbudowanego w określonym parametrze. Więcej informacji znajdziesz w artykule na temat realizacji z wykorzystaniem intencji skrótu.

<parametr> (dla <shortcut-fulfillment>)

Opcjonalny atrybut, który mapuje pojedynczy parametr BII na realizację skrótu dotyczącego wbudowanego asortymentu. Więcej informacji znajdziesz w artykule na temat realizacji z wykorzystaniem intencji skrótu.

Atrybut:

• android:name: nazwa parametru BII, który ma być powiązany z wewnętrzną realizacją skrótów dotyczących zasobów reklamowych. Nazwa powinna być polem na poziomie liścia parametru BII (np. menuItem.name).

<wycinek>

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

Schemat skrótu

W tabeli poniżej opisujemy atrybuty elementów shortcut, które służą do włączania działań w aplikacji. Gdy dodajesz tag, wszystkie jego atrybuty są wymagane, chyba że oznaczono je jako „opcjonalne”.

Tag shorts.xml	Zawarte w	Atrybuty
<shortcut>	<shortcuts>	android:shortcutId android:shortcutShortLabel android:shortcutLongLabel (opcjonalnie) android:icon (opcjonalnie)
<intent>	<shortcut>	android:action android:targetClass (opcjonalnie) android:targetPackage (opcjonalnie) android:data (opcjonalnie)
<capability-binding>	<shortcut>	android:key
<parameter-binding>	<capability-binding>	android:key (opcjonalnie) android:value
<extra>	<shortcut>	android:name (opcjonalnie) android:value Dotyczy tylko dopasowywania parametrów Enum.

Opis schematu skrótu

W tej sekcji opisujemy elementy schematu shortcut.

<skrót>

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

Atrybuty:

• android:shortcutId: identyfikator tego skrótu.
• android:shortcutShortLabel: zasób tekstowy reprezentujący krótki ciąg znaków. np. "@string/callDavidShort" reprezentujący wartość „Zadzwoń do Dawida”.
• android:shortcutLongLabel: zasób tekstowy reprezentujący długie wyrażenie skrótu. np. "@string/callDavidLong" reprezentujący wartość „Zadzwoń do Dawida”.

<zamiar>

Intencja Androida powiązana z tym skrótem. Ten skrót intent jest wykonywany, gdy użytkownik uruchomi ten skrót głosowo lub dotykowo.

Atrybuty intencji shortcut są identyczne z atrybutami capability intent.

<powiązanie możliwości>

Przypisuje shortcut do capability działań w aplikacji. Dodanie tego elementu do elementu shortcut umożliwia realizację go za pomocą polecenia Assistant.

Atrybuty:

• android:key: atrybut android:name elementu capability, z którym jest powiązany ten element shortcut. Przykład: actions.intent.CREATE_TAXI_RESERVATION.

<powiązanie parametrów>

Opcjonalny atrybut, który wiąże właściwość shortcut z pojedynczym parametrem w capability działań w aplikacji. Jeśli w polu shortcut zdefiniowany jest element parameter-binding, można użyć skrótu, aby do parametru BII dodać encję wbudowanego asortymentu. Więcej informacji znajdziesz w artykule Wbudowane zasoby reklamowe na potrzeby działań w aplikacji.

Atrybuty:

• android:key: nazwa parametru capability BII, z którym ma być powiązany ten skrót. Przykład: foodObservation.aboutFood.name.
• android:value: wartość entity. Może to być pojedynczy obiekt entity lub lista zasobów.

<ekstra>

Parametr extra łączy dane skrótu. Jedyne dane związane z elementami shortcut działań w aplikacji to sameAs. Adres URL w polu sameAs odnosi się do referencyjnej strony internetowej, która jednoznacznie identyfikuje dany element. Służy do określania wartości wyliczenia tylko wtedy, gdy typ parametru intencji jest podtypem schema.org/Enumeration. Jest on wymagany w przypadku pól parametrów, które są podtypami obiektu 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 Pasujące wartości parametrów wyliczonych.

Opcje realizacji intencji

Definiujesz elementy intent w elemencie <capability>, aby określić, jak Asystent odpowiada na polecenia głosowe użytkownika pasujące do danej możliwości lub je wykonuje. Istnieje kilka sposobów konfigurowania sposobu, w jaki intent uruchamia miejsce docelowe realizacji zamówienia w aplikacji w zależności od struktury nawigacji po aplikacji.

Dostępne są te opcje realizacji zamówienia:

• Intencje jednoznaczne: uruchom określony komponent aplikacji, definiując atrybuty targetClass i targetPackage dla intent. To jest zalecana metoda realizacji działań w aplikacji.

• Precyzyjne linki: możesz uruchamiać miejsca docelowe aplikacji za pomocą precyzyjnych linków na Androida. W tym celu zdefiniuj tag <url-template> w elemencie intent. Ta metoda jest przydatna, jeśli nawigacja po aplikacji korzysta już z precyzyjnych linków.

• Dane intencji: identyfikator URI realizacji możesz podać w atrybucie intent android:data. To pole zostanie zastąpione danymi <url-template>, jeśli ten tag jest też zdefiniowany w ramach intent.

Dane i dopasowywanie parametrów

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

Możesz też zadeklarować tag <url-template> w capability, który zawiera zmienne dla parametrów dynamicznych. Ten szablon jest mapowany na jedną z Twoich działań na Androida za pomocą adresu URL linków aplikacji, schematu niestandardowego lub adresu URL opartego na intencji.

Korzystanie z dodatków do intencji

Ten przykład pokazuje bezpośrednią intencję zdefiniowaną na potrzeby realizacji capability:

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Biorąc pod uwagę powyższy przykład, dla zapytania użytkownika takiego jak „OK Google, zamów latte z PrzykładowaAplikacja” aplikacja otrzymuje intent, który wywołuje komponent: targetPackage, targetClass. Komponent otrzymuje Dodatkowy z funkcją key = ”menu”, value = ”latte”.

Korzystanie z szablonu adresu URL w przypadku precyzyjnych linków na Androida

Jeśli Twoja aplikacja jest już w stanie obsługiwać adresy URL połączone z aplikacją z parametrami dynamicznymi, możesz zdefiniować <url-template> w zasadzie intent, aby generować precyzyjne linki na Androida. Poniższy przykład definiuje element <url-template>:

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Biorąc pod uwagę powyższy przykład, po wpisaniu zapytania użytkownika takiego jak „OK Google, zamów latte z PrzykładowaAplikacja” aplikacja otrzyma wygenerowany adres URL: „myapp://order?menu=latte”.

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 URL, którą chcesz zastąpić informacjami pochodzącymi od użytkownika. Wartość android:key musi występować w elemencie <url-template> i musi być ujęta w nawiasy klamrowe ({}).

Dopasuj wartości parametrów wyliczonych

Niektóre parametry BII zawierają wyliczone wartości w ramach intencji realizacji, np. obsługiwane wartości tekstowe w RECORD_FOOD_OBSERVATION BII. W przypadku tych parametrów Asystent dopasowuje zapytanie użytkownika („Śniadanie”) do elementu, którego wartość sameAs odpowiada adresowi URL schematu enum (https://schema.googleapis.com/MealTypeBreakfast). Aby powiązać wartości enum z obsługiwanym elementem entity, zadeklaruj powiązanie sameAs w pliku shortcut. W tym przykładzie pokazano powiązanie sameAs z wbudowanym skrótem elementu:

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

Jeśli w przykładzie powyżej funkcja RECORD_FOOD_OBSERVATION wywoła dopasowanie do posiłku typu „śniadanie”, z realizacją intent zostanie wysłany kod Extra:

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

Funkcje

W usłudze shortcuts.xml dostępne są poniższe funkcje akcji w aplikacji.

Wbudowane zasoby reklamowe na potrzeby działań w aplikacji

W przypadku niektórych parametrów BII można używać skrótów, aby kierować wyodrębnianie encji do zbioru obsługiwanych elementów określonych w elemencie shortcuts.xml, tzw. wbudowanych zasobów reklamowych. Więcej informacji znajdziesz w artykule Wbudowane zasoby reklamowe.

Zasoby reklamowe w internecie na potrzeby działań w aplikacji

W przypadku niektórych BII możesz użyć internetowych zasobów reklamowych jako metody generowania adresów URL na potrzeby realizacji. Zasoby reklamowe używają Twojej witryny do wykrywania adresów URL na potrzeby realizacji akcji w aplikacji. Ta funkcja jest najbardziej przydatna, gdy masz mocną stronę w internecie, a precyzyjne linki w aplikacji są uporządkowane wokół dostępnych publicznie treści z internetu.

Więcej informacji znajdziesz w artykule Internetowe zasoby reklamowe.

Niestandardowe zamiary

Intencje niestandardowe można zadeklarować w shortcuts.xml, aby włączyć w aplikacji funkcje głosowe, które nie pasują do dostępnych BII. Chociaż intencje niestandardowe są podobne pod względem funkcjonalności do definicji BII, w zasadzie shortcuts.xml niestandardowe intencje wymagają 2 dodatkowych atrybutów:

• app:queryPatterns: zasób tablicy deklarujący różne wzorce zapytań dla intencji niestandardowej.

• android:mimeType: typ parametru intencji niestandardowej. To pole nie jest wymagane w przypadku BII, gdy typ parametru jest znany. W przypadku niestandardowych parametrów intencji musi być zadeklarowany obsługiwany typ semantyczny.

Więcej informacji znajdziesz w artykule Intencje niestandardowe.