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ła funkcję [actions.intent.GET_FOOD_OBSERVATION][] w aplikacji, mówiąc „OK Google, zapytaj Aplikację X, co jadłem na obiad w zeszły 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. 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 foodObservation.forMeal, który raportuje wszystkie posiłki w danym dniu, na przykład „OK Google, zapytaj przykładowąaplikację, co jadłem na lunch”.

Uwaga: zastępcza intent, która nie wymaga obecności parametru, dla każdego capability. Te zastępcze Służą do zwiększania wygody użytkownika, umożliwiając skuteczne działania w przypadku niejasnych zapytań użytkowników, takich jak „OK Google, zapytaj PrzykładowaAplikacja, co jadłem”

;

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

Uwaga: jeśli używasz narzędzia do zaciemniania w przypadku pliku APK wersji, wyłącz zaciemnianie pliku shortcuts.xml aplikacji, korzystając z listy dozwolonych. Jeśli jeśli tego nie zrobisz, prawdopodobnie podczas przesyłania pliku APK do Konsola Google Play.

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.

Uwaga: Asystent może też wyświetlać użytkownikom dynamiczne skróty. Dynamiczna, są dostosowane do potrzeb użytkowników i mogą być tworzone i aktualizowane pod adresem w środowisku wykonawczym. Więcej informacji znajdziesz w artykule Przekazywanie skrótów dynamicznych do Asystenta.

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. Możesz na przykład zadeklarować skrót aplikacji „Rozpocznij bieg”, który wywołuje w aplikacji fitness opcję BII START_EXERCISE.

  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 elementów zawierają listę obsługiwanych wartości parametrów do obsługi zapytań głosowych dotyczących 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.

  Uwaga: statyczne skróty zadeklarowane jako skróty encji są usuwane przez LauncherApps API, co oznacza, że są dostępne dla programów uruchamiających Androida.

Schemat możliwości

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

Tag Shortcuts.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)
<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 element <intent>, aby obsłużyć wykonanie działania.

Atrybuty:

• android:name: identyfikator działania wbudowanej intencji (np. [actions.intent.GET_FOOD_OBSERVATION][]). 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ą.

Uwaga: wbudowane intencje działań w aplikacji różnią się od intencji w Androidzie. Model BII zapytanie użytkownika dotyczące zadania, które chce wykonać w aplikacji; Android, dla intencji, dla przeciwieństwa uruchamiają w niej miejsca docelowe z dołączonymi i dodaje kontekst. Deklarujesz capability tagów, aby zmapować BII na odpowiedni Androida umożliwia użytkownikom uruchomienie funkcji w aplikacji przez wywołanie metody BII za pomocą Asystenta.

<intent>

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

Atrybuty:

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

Uwaga: atrybuty android:targetClass i android:targetPackage są wymagane w przypadku intencji, które wyraźnie wskazują na Aktywność. Atrybut android:data może też być służy do zdefiniowania działania docelowego. Więcej informacji: Opcje realizacji intencji

<szablon-url>

Szablon do tworzenia identyfikatora URI precyzyjnego linku do otwartego na urządzeniu. Jeśli wszystkie wymagane parametry są dostępne, szablon może zostać rozszerzony o wbudowane parametry intencji. 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	Rozwinięta wartość
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.

Uwaga: <url-template> to opcjonalna metoda kierowania na aktywność w intent. Więcej informacji znajdziesz w artykule Opcje realizacji intencji.

<ekstra>

Określa dodatkowe dane dla: intent. W przypadku działań w aplikacji to pole jest używane tylko do: włączyć [wywołanie 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/*. To pole jest wymagane tylko w przypadku parametrów intencji niestandardowych.
• 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 jest niedostępny, Asystent próbuje spełnić zapytanie użytkownika, używając następnego intent zdefiniowanego dla capability.

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

<slice>

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.

<shortcut>

Android <shortcut> zdefiniowany w aplikacji shortcuts.xml z określonymi atrybutami istotne dla akcji 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ó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 "@string/callDavidLong" oznacza wartość „Zadzwoń do Davida”.

<intent>

Intencje Androida powiązane 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 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 elementu capability w Element shortcut jest powiązany z. Przykład: actions.intent.START_EXERCISE

<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: exercise.name.
• android:value: wartość entity. Może to być pojedynczy entity lub listę zasobów.

<ekstra>

Dane extra pakietu skrótu. sameAs to jedyne dane istotne dla elementów shortcut działań 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: uruchamiaj miejsca docelowe w aplikacji za pomocą precyzyjnych linków na Androida, definiując 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.

Uwaga: te opcje realizacji zamówień wzajemnie się wykluczają. Jeśli na przykład określ jednoznacznie intent za pomocą elementów targetClass i targetPackage, nie musisz też określać <url-template>.

Dane i dopasowanie parametrów

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 pliku capability, który zawiera symbole zastępcze 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 dodatków intencji

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

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

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 = "exercise", value = "Running".

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

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://start?exercise=Bieganie”.

Uwaga: jeśli wygenerowany adres URL zdarzenia intent używający <url-template> dla atrybutu realizacja jest powiązana z aplikacją, a w polu kierowania zostały dodane odpowiednie filtry intencji. AndroidManifest.xml plik zasobów, targetClass i targetActivity atrybutów nie muszą być zdefiniowane w tabeli intent.

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 występować w elementach <url-template> i być ujęta w nawiasy klamrowe ({}).

Dopasuj wartości parametrów wyliczane

Niektóre parametry BII podają wartości z enumeracji, na przykład obsługiwane wartości tekstowe parametru BII RECORD_FOOD_OBSERVATION. 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. Ten przykład pokazuje powiązanie sameAs z skrótem elementu wbudowanego:

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

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. W przypadku parametrów niestandardowych intencji musisz zadeklarować obsługiwany typ semantyczny.

Więcej informacji znajdziesz w artykule Intencje niestandardowe.