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ć:
W pliku manifestu aplikacji (
AndroidManifest.xml
) znajdź aktywność, której filtry intencji są ustawione na działanieandroid.intent.action.MAIN
i kategorięandroid.intent.category.LAUNCHER
.Dodaj odwołanie do funkcji
shortcuts.xml
w plikuAndroidManifest.xml
za pomocą tagu<meta-data>
w elemencieActivity
, który zawiera filtry intencji zarówno dlaMAIN
, jak iLAUNCHER
:<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ówintent
. 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
ilongLabel
, 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 elementemcapability
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 parametremexercise.name
BII możliwościSTART_EXERCISE
. Jeśli wypowiedź użytkownika pasuje do encji, do intencji zamiast nieprzetworzonej wartości zapytania użytkownika jest przekazywany identyfikatorshortcutId
.Skróty
Entity
nie definiują atrybutówintent
,shortLabel
anilongLabel
, 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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Dotyczy tylko wywołania aplikacji na pierwszym planie |
<parameter> |
<intent> |
|
<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
: typAction
intencji. Domyślna wartość toACTION_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 wintent
.
<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"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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 parametremintent
. 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 parametrumessage.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 parametruintent
zdefiniowanego w polucapability
.
<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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
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
: atrybutandroid:name
elementucapability
, z którym jest powiązany ten elementshortcut
. 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 parametrucapability
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 obiektentity
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 URLsameAs
.
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
itargetPackage
dlaintent
. 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 elemencieintent
. 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 ramachintent
.
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.