Utwórz shortcuts.xml

Gdy zidentyfikujesz funkcje w aplikacji i odpowiadającą im intencję wbudowaną (BII) do wdrożenia należy zadeklarować BII, którą funkcja obsługuje, definiując element capability w pliku zasobów shortcuts.xml. Deklarowanie BII jako capability rejestruje obsługę tej semantycznej intencji w aplikacji, umożliwia realizację zapytań głosowych intencji za pomocą Asystenta Google.

Asystent używa przetwarzania języka naturalnego do wyodrębniania parametrów od użytkownika zapytania. Informacje o intencjach wbudowanych zawierają listę pól, do których należy każdy komponent BII wyodrębniania z powiązanego zapytania użytkownika. Jeśli na przykład użytkownik wywołuje funkcję actions.intent.ORDER_MENU_ITEM w aplikacji przez mówiąc: „OK Google, zamów pizzę w PrzykładowaKawiarnia w aplikacji Przykładowa aplikacja”, Asystent wyodrębnia z żądania 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 W funkcji można zdefiniować co najmniej 1 element intent uwzględnia różne sposoby wywoływania BII przez użytkownika. Na przykład: może zdefiniować realizację intent, która wymaga obu parametrów BII w powyżej. Następnie możesz zdefiniować drugą intencję, która wymaga pojedynczego BII menuItem.name, który wyświetla opcje restauracji w pobliżu, jeśli użytkownik tworzy prostsze zapytanie, na przykład „OK Google, zamów pizzę w PrzykładowaAplikacja”.

;

Omówienie

Aby skonfigurować akcje w aplikacji, użyj pliku shortcuts.xml umieszczonego w Twojej aplikacji. katalogu res/xml projektu, a następnie utworzenie odwołania do shortcuts.xml w manifeście aplikacji. Dodaj odwołanie do: shortcuts.xml w manifeście aplikacji wykonując te czynności:

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

2. Dodaj odwołanie do dokumentu shortcuts.xml w dokumencie AndroidManifest.xml za pomocą Tag <meta-data> w lokalizacji Activity, który ma intencję filtry MAIN i LAUNCHER w następujący sposób:

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

W powyższym przykładzie jest deklarowany zasób XML dla pliku xml/shortcuts.xml plik APK. Więcej informacji o konfigurowaniu skrótów znajdziesz w sekcji Utwórz statyczne skróty w dokumentacji dla programistów aplikacji na Androida.

Biblioteka Jetpack androidx.core:core:1.6.0 (co najmniej) jest wymagane w projekcie na Androida, aby uniknąć błędów kompilacji podczas określania funkcji akcji w aplikacji w shortcuts.xml. Więcej informacji: Pierwsze kroki z Androidem Jetpack

Skróty statyczne

Podczas określania capability możesz zadeklarować statyczne elementy shortcut w shortcuts.xml. Skróty statyczne są przetwarzane przez Asystenta, gdy prześlesz wersję do Konsoli Google Play. Ponieważ statyczne skróty można tworzyć i aktualizować tylko przez tworzenie nowych wersji, są najbardziej przydatne do wyróżnienia typowych działań i treści w aplikacji.

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

• Skróty dotyczące funkcji. Utwórz skróty, które będą uruchamiać instancję Twojej bazy danych Funkcja capability zawierająca wstępnie zdefiniowane wartości parametru intent. Przykład: możesz zadeklarować skrót do aplikacji „Rozpocznij uruchomienie” który wywołuje metodę START_EXERCISE BII w aplikacji do fitnessu.

  Te skróty zawierają atrybuty intent, shortLabel i longLabel, co sprawia, że mogą być sugerowane i realizowane jako elementy aktywnie np. za pomocą Asystenta lub po przytrzymaniu ikony aplikacji na urządzeniu z Androidem. program uruchamiający. Skrót do działania może służyć też jako skrót do elementu, szczegółowe poniżej, powiązując go z elementem capability za pomocą <capability-binding>.

• Skróty do jednostek. Skróty encji zawierają listę obsługiwanych parametrów wartości zapytania głosowego capability. Na przykład jednostka skrót z listą typów ćwiczeń („Wędrówka”, „bieganie” itp.) powiązanych z exercise.name parametru BII parametru START_EXERCISE. działania. Jeśli wypowiedzi użytkownika pasują do encji, identyfikator shortcutId to przekazywane do intencji zamiast do nieprzetworzonej wartości zapytania użytkownika.

  Entity skrótu nie definiuje intent, shortLabel ani longLabel i jako takie nie są sugerowane na aktywnych platformach. Dla: Więcej informacji znajdziesz w artykule Wbudowane zasoby reklamowe w działaniach w aplikacji.

Schemat funkcji

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

Tag Skróty.xml	Zawarte w	Atrybuty
<capability>	<shortcuts>	android:name app:queryPatterns (dotyczy tylko 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 Ma zastosowanie tylko w przypadku wywołań aplikacji na pierwszym planie.
<parameter>	<intent>	android:name android:key android:mimeType (dotyczy tylko niestandardowych intencji) android:required (opcjonalnie) app:shortcutMatchRequired (opcjonalnie)
<data>	<parameter>	android:pathPattern (dotyczy tylko internetowych zasobów reklamowych)
<shortcut-fulfillment>	<capability>	Ma zastosowanie tylko w przypadku wbudowanych zasobów reklamowych.
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	Dotyczy tylko wycinków Androida.

Opis schematu funkcji

W tej sekcji opisano elementy schematu capability.

<capability>

capability, który określa intencję w działaniu aplikacji obsługiwaną przez aplikację. Każdy Element <capability> w pliku shortcuts.xml musi zawierać co najmniej 1 <intent> do obsługi realizacji działania.

Atrybuty:

• android:name: identyfikator działania wbudowanej intencji (np. actions.intent.CREATE_TAXI_RESERVATION). Listę obsługiwanych funkcji Więcej informacji znajdziesz w dokumentacji intencji wbudowanych.
• app:queryPatterns: zasób tablicy ciągu zapytań oczekiwanych z interfejsu użytkownika w przypadku danej intencji. Ten atrybut ma zastosowanie tylko do: niestandardowe intencje, ponieważ wskaźniki BII obejmują już modele sposób, w jaki użytkownicy wyrażają swoje zamiary, lub informacje których szukają.

.

<intent>

Element Androida intent określający sposób zapytania użytkownika realizowanych za pomocą funkcji w aplikacji. Deweloperzy mogą podać kilka <intent> w tagach capability. Asystent próbuje odpowiedzieć na zapytanie użytkownika, używając funkcji pierwsze <intent> w capability, dla których są dostępna.

Atrybuty:

• android:action: typ intencji Action. 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 dla przykład: "com.example.food"
• android:data: to pole zostaje zastąpione przez wartość <url-template> jeśli ten tag jest zadeklarowany w intent.

.

<szablon-url>

Szablon do tworzenia identyfikatora URI precyzyjnego linku do otwartego na urządzeniu. Szablon można rozwinąć za pomocą intencji wbudowanej jeśli wszystkie parametry wymagane dla szablonu są dostępne. Dla: przykładowego szablonu adresu URL HTTP znajdziesz w Artykuł w Wikipedii o szablonach adresów URL. format szablonu jest zgodny ze specyfikacją szablonu identyfikatora 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>

Określa dodatkowe dane dla: intent. W przypadku działań w aplikacji to pole jest używane tylko do: włącz wywoływanie aplikacji na pierwszym planie dla: capability.

<parametr>

Mapuje parametr BII na wartości parametrów intencji. Więcej informacji: Dane i dopasowanie parametrów

Atrybuty:

• android:name: nazwa parametru BII, który ma być powiązany z parametrem intent. . Nazwa powinna być polem na poziomie liścia parametru BII (na np. foodObservation.aboutFood.name).
• android:key: zdefiniowany przez dewelopera klucz wartości parametru BII. Przykład: możesz określić contact_name dla message.recipient.name BII .
• android:mimeType: typ MIME parametru, na przykład text/*. Ten jest wymagane tylko w przypadku parametrów niestandardowych intencji.
• android:required: określa, czy zapytanie użytkownika musi zawierać tę wartość dla tej intencji, który ma być używany do realizacji. Jeśli parametr to nie dostępne, Asystent próbuje odpowiedzieć na pytanie użytkownika, używając kolejnych argumentów Zdefiniowano intent dla: capability.

<dane>

Przypisuje internetowe zasoby reklamowe do elementu parameter.

Atrybut:

• android:pathPattern: wzorzec adresu URL entity adresów URL, które mają zostać zwrócone przez zasobów reklamowych w internecie. Ten atrybut obsługuje dwa symbole wieloznaczne:

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

  • .*: kropka z gwiazdką odpowiada dowolnej sekwencji zero lub więcej znaków.

  • Znaki Escape są potrzebne tylko w przypadku liter * i \, których może zostać zwrócony jako \\* i \\\\.

<skrót-realizacja>

Określa, że element intent zdefiniowany w skrócie wbudowanych zasobów reklamowych dla określonego parametru, który będzie używany do realizacji. Więcej informacji znajdziesz w sekcji Realizacja za pomocą intencji skrótów.

<parametr> (przez <shortcut-fulfillment>)

Atrybut opcjonalny, który mapuje pojedynczy parametr BII na wbudowane zasoby reklamowe realizację skrótu. Więcej informacji znajdziesz w sekcji Realizacja za pomocą intencji skrótów.

Atrybut:

• android:name: nazwa parametru BII, który ma zostać powiązany z wbudowanymi zasobami reklamowymi realizację skrótu. Nazwa powinna być polem na poziomie liścia BII (np. menuItem.name).

<wycinek>

Pozwala Asystentowi umieszczać wynik zapytania pasującego do tego identyfikatora capability jako wycinek Androida. Więcej informacji: Integrowanie akcji w aplikacji z wycinkami Androida

Schemat skrótu

W tej tabeli opisujemy atrybuty elementów shortcut, które są używane do: włączyć akcje w aplikacji, Po dodaniu tagu wszystkie jego atrybuty są wymagane, o ile nie zostały oznaczone jako „opcjonalne”.

Tag Skróty.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 dopasowania parametrów wyliczeniowych.

Opis schematu skrótu

W tej sekcji opisano elementy schematu shortcut.

<skrót>

Android <shortcut> zdefiniowany w aplikacji shortcuts.xml z określonymi atrybutami istotne dla akcji w aplikacji. shortcutShortLabel – ciągi znaków i shortcutLongLabel odwołują się do pól pakietu APK zasoby w postaci ciągów znaków.

Atrybuty:

• android:shortcutId: identyfikator tego skrótu.
• android:shortcutShortLabel: zasób ciągu znaków reprezentujący krótki skrót do wyrażenia. Na przykład "@string/callDavidShort" reprezentujący wartość „Call” Davida”.
• android:shortcutLongLabel: zasób ciągu znaków reprezentujący długi skrót do wyrażenia. Na przykład zapis "@string/callDavidLong" reprezentujący wartość „Utwórz do Dawida”.

<intent>

Intencja w Androidzie powiązana z tym skrótem. Polecenie intent jest wykonywane, gdy użytkownik uruchomi ten skrót głosowo lub dotykiem.

Atrybuty intencji shortcut są takie same jak atrybuty intencji capability intent .

<capability-binding>

Powiązanie elementu shortcut z akcjami w aplikacji capability. Dodawanie tego elementu do: shortcut umożliwia realizację poleceń głosowych za pomocą usługi Assistant.

Atrybuty:

• android:key: atrybut android:name elementu capability w Element shortcut jest powiązany z. Przykład: actions.intent.CREATE_TAXI_RESERVATION

<powiązanie parametrów>

Atrybut opcjonalny, który wiąże wartość shortcut z pojedynczym parametrem aplikacji. Działania capability. Jeśli dla właściwości shortcut zdefiniowano parameter-binding, parametr możesz użyć skrótu, aby udostępnić wbudowaną jednostkę reklamową do parametru BII. Więcej informacji znajdziesz w artykule Wbudowane zasoby reklamowe w działaniach w aplikacji.

Atrybuty:

• android:key: nazwa parametru BII capability do powiązania ten skrót. Na przykład: foodObservation.aboutFood.name.
• android:value: wartość entity. Może to być pojedynczy entity lub listę zasobów.

<ekstra>

Dane pakietu extra dla skrótu. Jedyne dane to sameAs. istotne w przypadku elementów shortcut Akcji w aplikacji. Adres URL sameAs odnosi się do jednoznacznie identyfikują dany podmiot. Służy do określania wartość wyliczeniową tylko wtedy, gdy typ parametru intencji jest podtypem schema.org/Enumeration Jest wymagany w przypadku pól parametrów których typy są podtypami obiektu schema.org/Enumeration (na przykład: MealTypeBreakfast).

Atrybuty:

• android:key – obsługiwana wartość w przypadku akcji w aplikacji to: sameAs
• android:value: wartość adresu URL sameAs.

Więcej informacji znajdziesz w sekcji Dopasowanie wartości parametrów wyliczanych.

Opcje realizacji intencji

Definiujesz elementy intent w elemencie <capability>, aby zadeklarować, jak Asystent reaguje na polecenia głosowe pasujące do danej funkcji lub wykonuje je; OK jest kilka sposobów konfigurowania sposobu, w jaki intent uruchamia miejsce docelowe realizacji w zależności od struktury nawigacji w aplikacji.

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

• Intencje jawne: uruchom określony komponent aplikacji, definiując Atrybuty targetClass i targetPackage dla intent. Jest to zalecana metoda realizacji akcji w aplikacji.

• Precyzyjne linki: uruchom miejsca docelowe aplikacji za pomocą precyzyjnych linków na Androida: tag <url-template> w elemencie intent. Ten jest przydatna, jeśli nawigacja w aplikacji wymaga już użycia precyzyjnych linków.

• Dane intencji: w intent możesz podać identyfikator URI realizacji transakcji. android:data. To pole jest zastąpione danymi <url-template> jeśli ten tag jest także zdefiniowany w elemencie intent.

.

Dane i dopasowanie parametrów

Domyślnie Asystent wysyła parametry BII wyodrębnione z zapytania użytkownika do jako dane extra Androida intent zdefiniowanego w dokumencie capability.

Możesz też zadeklarować tag <url-template> w sekcji capability, który zawiera zmienne parametrów dynamicznych. Ten szablon mapuje się na jedną z Twoich aktywności na Androidzie za pomocą adresu URL linków aplikacji, schemat niestandardowy lub adres URL oparty na intencjach.

Korzystanie z dodatków intencji

Ten przykład ilustruje wyraźną intencję zdefiniowaną dla pola capability realizacja:

<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, w przypadku zapytania użytkownika takiego jak „OK Google, zamów latte od: exampleApp," aplikacja otrzymuje żądanie intent, które wywołuje komponent: targetPackage, targetClass. Komponent otrzymuje dodatek o key = ”menu”, value = ”latte”.

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

Jeśli aplikacja obsługuje już połączone z aplikacją adresy URL z wykorzystaniem parametrów dynamicznych, możesz zdefiniować <url-template> w intent, aby wygenerować Androida precyzyjne linki umożliwiające realizację zamówień. Poniższy przykład definiuje <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, w przypadku zapytania użytkownika takiego jak „OK Google, zamów latte” z przykładowej aplikacji, aplikacja otrzyma wygenerowany adres URL: „myapp://order?menu=latte”.

Aby zmapować parametr BII na pozycję w adresie URL, użyj funkcji Atrybut android:name tagu <parameter>. Ten atrybut odpowiada wartości android:key w szablonie URL, który chcesz zastąp informacjami od użytkownika. Wartość android:key musi być podana w polu <url-template> i umieszczone w nawiasach klamrowych ({}).

Dopasuj wartości parametrów wyliczane

Niektóre parametry BII udostępniają wartości wyliczane do intencji realizacji, przykład obsługiwanych wartości tekstowych w narzędziu RECORD_FOOD_OBSERVATION BII. Dla: te parametry, Asystent dopasuje zapytanie użytkownika („Śniadanie”) do encja, której wartość sameAs pasuje do adresu URL schematu wyliczeniowego (https://schema.googleapis.com/MealTypeBreakfast). Aby powiązać wyliczenie wartości obsługiwanych wartości entity, deklarujesz powiązanie sameAs w shortcut. Poniższa próbka przedstawia powiązanie sameAs dla skrót do jednostki wbudowanej:

<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 powyższym przykładzie możliwość RECORD_FOOD_OBSERVATION aktywuje wywołanie wybierz „śniadanie” rodzaj posiłku, następujący dodatek jest wysyłany wraz z realizacja intent:

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

Funkcje

Poniższe akcje w aplikacji są dostępne w usłudze shortcuts.xml.

Wbudowane zasoby reklamowe do działań w aplikacji

W przypadku niektórych parametrów BII można używać skrótów do kierowania encji wyodrębnienia do zbioru obsługiwanych encji określonych w shortcuts.xml, znanych jako zasobów reklamowych. Szczegółowe informacje znajdziesz w artykule Wbudowane zasoby reklamowe.

Internetowe zasoby reklamowe na potrzeby akcji w aplikacji

W przypadku niektórych BII możesz użyć internetowych zasobów reklamowych jako metody generowanie adresów URL na potrzeby realizacji. Zasoby reklamowe w internecie korzystają z Twojej witryny, aby wykrywać Adresy URL do realizacji akcji w aplikacji. Ta funkcja jest najbardziej przydatna, gdy masz aby zadbać o widoczność w internecie, a precyzyjne linki w aplikacji są uporządkowane pod kątem dostępnych treści internetowych.

Szczegółowe informacje znajdziesz w artykule Internetowe zasoby reklamowe.

Niestandardowi odbiorcy o podobnych zamiarach

W polu shortcuts.xml można zadeklarować niestandardowe intencje, aby głosowo włączać funkcje w: które nie pasują do dostępnych danych BII. Choć podobnie w stosunku do definicji BII, intencje niestandardowe wymagają 2 dodatkowych atrybuty w shortcuts.xml:

• app:queryPatterns: zasób tablicowy deklarujący różne wzorce zapytań w przypadku intencji niestandardowej.

• android:mimeType: typ parametru intencji niestandardowej. To pole jest nie jest wymagany w przypadku BII, gdzie typ parametru jest znany. Niestandardowi odbiorcy o podobnych zamiarach musisz zadeklarować obsługiwany typ semantyczny.

Więcej informacji znajdziesz w artykule Intencje niestandardowe.