Wbudowane zasoby reklamowe

Podczas wdrażania akcji w aplikacji dla swojej aplikacji na Androida może się okazać, że musisz obsługiwać żądania, które są odmianami motywu. Załóżmy na przykład, że Twoja aplikacja do fitnessu ma wbudowaną intencję START_EXERCISE (BII), która pozwala użytkownikom rozpoczynać różne treningi za pomocą poleceń głosowych do Asystenta: „OK Google, rozpocznij bieg w przykładowej aplikacji”.

Spełnienie tej intencji wymaga dopasowania żądań do każdego rodzaju treningu, w tym różnych odmian takich jak „bieg”, „sprint” czy „wyścig”. Ta logika szybko staje się niewygodna w miarę zwiększania liczby obsługiwanych treningów.

W przypadku obsługiwanych identyfikatorów BII, takich jak START_EXERCISE, możesz uniknąć tego złożonego mechanizmu dopasowywania, korzystając z wbudowanych zasobów reklamowych. Wbudowane zasoby reklamowe to zestaw statycznych skrótów na Androida zdefiniowanych w shortcuts.xml, które reprezentują funkcje i zawartość aplikacji.

Każdy skrót zawiera identyfikator elementu oraz listę synonimów reprezentujących różne sposoby odwoływania się do elementu. Podczas wywoływania usługa BII porównuje podany przez użytkownika parametr BII z listą synonimów. Po znalezieniu dopasowania parametr BII jest aktualizowany na identyfikator elementu odpowiedniego skrótu.

Wbudowane zasoby reklamowe pozwalają Asystentowi Google uprościć wartości parametrów BII podawane aplikacji podczas wywoływania akcji w aplikacji.

Wbudowane asortymenty pełnią funkcję takich jak tabele przeglądowe parametrów BII, które określają różne sposoby odwołania się do funkcji lub treści w aplikacji za pomocą zdefiniowanych przez Ciebie identyfikatorów produktów. Upraszczają one logikę dopasowywania żądań aplikacji, ponieważ pozwalają realizacji przewidywać identyfikatory produktów na podstawie parametrów BII.

Rysunek 1. Schemat blokowy funkcji START_EXERCISE, która korzysta z wbudowanych zasobów reklamowych do interpretowania podanych przez użytkownika nazw treningów na potrzeby obsługiwanych typów ćwiczeń w aplikacji.

Uwaga: wbudowane zasoby reklamowe są obsługiwane przez określone parametry niektórych identyfikatorów BII. Szczegółowe informacje znajdziesz w sekcji „Dostępność zasobów reklamowych według pola” w każdej usłudze BII w dokumentacji analityki biznesowej.

Ograniczenia i alternatywy

Wbudowane skróty do zasobów reklamowych podlegają tym ograniczeniom:

• Limit skrótów: w każdej aplikacji można zdefiniować maksymalnie 1000 wbudowanych skrótów zasobów reklamowych.
• Limit synonimów: każdy wbudowany skrót do zasobów reklamowych może zawierać maksymalnie 20 wartości synonimów.
• Definicja statyczna: skróty do wbudowanych zasobów reklamowych są statycznie zadeklarowane w shortcuts.xml i można je aktualizować tylko po opublikowaniu nowej wersji aplikacji.

Biorąc pod uwagę wymóg konfiguracji statycznej, wbudowane zasoby reklamowe najlepiej nadają się do udostępniania Asystentowi niezbyt często zmieniających się, niespersonalizowanych informacji z aplikacji, takich jak pozycje menu, trasy autobusów czy rozmiary napojów. W przypadku innych rodzajów treści rozważ te alternatywne rozwiązania:

• Zasoby reklamowe w internecie: pozwalają Asystentowi wysyłać zapytania do publicznych treści internetowych podczas dopasowywania zapytań użytkowników do obsługiwanych identyfikatorów treści aplikacji. Zapytania o zasoby reklamowe w internecie są wykonywane w czasie rzeczywistym podczas wywołania, co pozwala rozszerzyć katalogi produktów, posty w mediach społecznościowych i inne często aktualizowane treści do Asystenta.

• Skróty dynamiczne: umożliwiają rozszerzanie asortymentu spersonalizowanych treści z aplikacji na Asystenta. Dynamiczne skróty pozwalają użytkownikom szybko odtworzyć typowe czynności, takie jak zmiana kolejności ulubionego napoju w aplikacji do zamawiania jedzenia czy przeglądanie listy zakupów w aplikacji do robienia notatek.

Tworzenie wbudowanych zasobów reklamowych

Wbudowane zasoby reklamowe upraszczają tworzenie aplikacji, ponieważ dają Asystentowi poręczny sposób tłumaczenia różnych sposobów, w jakie użytkownicy proszą o treści i funkcje aplikacji, na przewidywalne identyfikatory, których oczekuje aplikacja. Załóżmy na przykład, że Twoja aplikacja oferuje różne treningi, do których użytkownicy mogą zacząć używać głosu, i wymaga od użytkowników wysyłania następujących żądań w przypadku tego samego rodzaju ćwiczeń:

• OK Google, rozpocznij uruchomienie w przykładowej aplikacji.
• OK Google, rozpocznij pobieganie w przykładowej aplikacji.

W ramach wbudowanego skrótu do zasobów reklamowych ustawiasz shortcutId na "CARDIO_RUN", czyli identyfikator ćwiczenia oczekiwany przez Twoją aplikację. Potem określasz „bieganie” i „bieganie” jako synonimy powiązane z shortcutId. Następnie, gdy użytkownik wywoła akcję w aplikacji za pomocą poprzednich zapytań, Asystent użyje identyfikatora "CARDIO_RUN" parametru BII podczas generowania intencji realizacji.

Ten przypadek jest implementowany przez poniższy fragment kodu z przykładowego pliku app/res/shortcuts.xml:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

W poprzednim przykładzie wbudowane zasoby reklamowe shortcut deklarują tag <parameter-binding> w elemencie <capability-binding>, łącząc go z parametrem exercise.name BII zdefiniowanym w <capability>.

Zasób tablicy ciągów znaków @array/run_names określa listę synonimów w elemencie res/values/arrays.xml, którą Asystent rozpoznaje i mapuje na identyfikator elementu "CARDIO_RUN":

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

Jeśli dla danej możliwości podany jest element <url-template>, w wygenerowanym adresie URL w odpowiednim miejscu zastępczym parametru jest wstawiony shortcutId dla pasującej wartości. Ten przypadek implementuje ten kod z przykładowego pliku app/res/shortcuts.xml:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

W poprzednim przykładzie Asystent generuje precyzyjny link do realizacji myapp://workout?exercise=CARDIO_RUN.

Uwaga: wbudowany asortyment obsługuje maksymalnie 1 element parameter na realizację intent elementu capability.

Realizacja z wykorzystaniem intencji skrótów

Domyślnie skrót udostępnia wartość shortcutId pasującej wartości wbudowanych zasobów reklamowych do elementu intent typu capability, z którym skrót jest powiązany, tak jak wskazano w tagu <capability-binding> skrótu. Możesz też określić, że intent zdefiniowany w skrócie ma być używany do realizacji, dodając tag <shortcut-fulfillment> do capability.

Ten kod z przykładowego pliku app/res/shortcuts.xml implementuje realizację skrótu:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

Jeśli w poprzednim przykładzie zapytanie użytkownika odpowiada wartości wbudowanego asortymentu w parametrze exercise.name, tag <shortcut-fulfillment> określa, że do realizacji jest używany skrót intent powiązany ze skrótem.

Uwaga: każdy wbudowany zasób reklamowy <shortcut>, który ma służyć do skróconej realizacji, musi zawierać realizację <intent>. Aby uniknąć błędów realizacji, nie używaj skrótów, które nie zawierają elementów intencji związanych z realizacją skrótu.

Wbudowane zasoby reklamowe dla funkcji otwartej aplikacji BII

Chociaż wbudowane zasoby reklamowe są zwykle opcjonalną funkcją w usługach BBI, które je obsługują, jest ona wymagana w przypadku niektórych identyfikatorów BII, np. OPEN_APP_FEATURE. Ten często używany wskaźnik BII pozwala użytkownikom za pomocą Asystenta tworzyć precyzyjne linki do konkretnych funkcji aplikacji. Funkcja otwartej aplikacji BII wymaga wbudowanych zasobów reklamowych z nazwami funkcji aplikacji w celu weryfikacji, czy istnieje funkcja zgłoszona przez użytkownika przed precyzyjnym linkiem użytkownika do aplikacji.

Poniższy kod z przykładowego pliku app/res/shortcuts.xml implementuje ten skrót BII z jednym skrótem reprezentującym funkcję stanu zamówienia w aplikacji:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

Zasoby tablicy z ciągami znaków w obiekcie res/values/arrays.xml, @array/order_status_names określają listę synonimów tej funkcji:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

Gdy to zrobisz, Asystent może wykorzystać różne wyrażenia dotyczące tej samej funkcji:

• „OK Google, pokaż stan mojego zamówienia w przykładowej aplikacji”
• „OK Google, pokaż moje zamówienia w przykładowej aplikacji”
• „OK Google, pokaż moją historię zamówień w Przykładowa aplikacja”

Testowanie wbudowanych zasobów reklamowych

Przetestuj swoje zasoby reklamowe, sprawdzając wartości parametrów BII podawane przez Asystenta w aplikacji przy jednoczesnym wykorzystaniu odpowiednich możliwości akcji w aplikacji. Wbudowane zasoby reklamowe polegają na zastępowaniu podanej przez użytkownika wartości parametru BII powiązanego z zasobami reklamowymi wartością shortcutId pasującego skrótu do zasobów reklamowych.

Na przykład funkcja START_EXERCISE BII może korzystać z wbudowanych zasobów reklamowych do translacji podanego przez użytkownika parametru BII „run” na odpowiedni identyfikator ćwiczenia "CARDIO_RUN".

Wtyczka Asystenta Google umożliwia wyświetlanie podglądu działań w aplikacji powiązanych z zasobami reklamowymi w Asystencie na urządzeniu testowym. Przetestuj swoje zasoby reklamowe za pomocą wtyczki, wykonując te czynności:

1. Skonfiguruj parametry związane z zasobami reklamowymi w możliwości BII, korzystając z synonimów powiązanych z wbudowanymi zasobami reklamowymi.
2. Aktywuj BII z wtyczki, wywołując go na urządzeniu testowym.
3. Sprawdź wynikowe wartości parametrów podawane aplikacji przez Asystenta podczas wykonywania akcji w aplikacji.