Wywołanie aplikacji na pierwszym planie

Akcje w aplikacji umożliwiają użytkownikom rozmawianie z Asystentem Google i przechodzenie bezpośrednio do konkretnych miejsc w aplikacji. Wystarczy, że powiesz na przykład „OK Google, zamów przejazd w przykładowej aplikacji”. Wywoływanie aplikacji na pierwszym planie umożliwia jeszcze lepsze wrażenia użytkowników, którzy mają już otwartą aplikację.

Wywołanie aplikacji na pierwszym planie umożliwia dopasowywanie intencji wbudowanych (BII) bez konieczności wymowy nazwy aplikacji, gdy konkretna aktywność działa na pierwszym planie urządzenia.

Na przykład użytkownik, który wyświetla na pierwszym planie aplikację do wspólnych przejazdów, mówi lub wpisuje do Asystenta Google „Zamów przejazd do Mountain View”. Aplikacja używa tych danych do ustawienia pola docelowego na Mountain View. Następnie, gdy użytkownik powie lub wpisze „Zamów przejazd z WAW”, aplikacja może ustawić miejsce odbioru, zachowując jednocześnie stan swojej aplikacji.

Ograniczenia

Wywoływanie aplikacji na pierwszym planie jest dostępne tylko w przypadku tych interfejsów BII:

• actions.intent.CREATE_MONEY_TRANSFER
• actions.intent.CREATE_TAXI_RESERVATION
• actions.intent.OPEN_APP_FEATURE
• actions.intent.ORDER_MENU_ITEM
• actions.intent.PAUSE_EXERCISE
• actions.intent.RECORD_EXERCISE
• actions.intent.RECORD_FOOD_OBSERVATION
• actions.intent.RESUME_EXERCISE
• actions.intent.START_EXERCISE
• actions.intent.STOP_EXERCISE

Informacje o obsłudze języka i przykładowe zapytania dotyczące wywoływania aplikacji na pierwszym planie w przypadku konkretnego BII znajdziesz w dokumentacji intencji wbudowanej.

Obsługuj wywoływanie aplikacji na pierwszym planie

Dodanie obsługi wywoływania aplikacji na pierwszym planie obejmuje dodanie działania realizacji na podstawie żądanej aktywności na pierwszym planie. Gdy aktywność znajduje się na pierwszym planie i jest wywoływane akcja w aplikacji, Asystent przekazuje intencję precyzyjnego linku z dodatkową flagą, aby aplikacja mogła zaktualizować stan.

Aby wdrożyć wywoływanie aplikacji na pierwszym planie w BII, wykonaj te czynności:

1. W pliku shortcuts.xml dodaj do BII <capability> tag <intent>, który ma obsługiwać wywoływanie aplikacji na pierwszym planie.
2. W tagu <intent> dodaj tag <extra>.
3. W tagu <extra> ustaw wartość android:key na "requiredForegroundActivity", a jako wartość android:value ustaw działanie, które ma znajdować się na pierwszym planie. Określ działanie bez skrótów klas – wpisz nazwę pakietu aplikacji i ukośnik (/) i nazwę aktywności: APP_PACKAGE_NAME/ACTIVITY_NAME
4. W aktywności na pierwszym planie określonej dla elementu "requiredForegroundActivity" zaimplementuj metodę onNewIntent(), aby obsługiwać intencję precyzyjnego linku z ustawioną flagą SINGLE_TOP. Gdy określona aktywność jest na pierwszym planie, Asystent przekazuje intencję precyzyjnego linku z tą flagą jako realizację.
5. Traktuj wywołania funkcji onNewIntent() jako aktualizacje aktywności na pierwszym planie i zarządzaj stanem tej aktywności za pomocą parametrów wyodrębnionych z precyzyjnego linku.

Jeśli Twoja aplikacja używa aktywności routera, aby umożliwić wszystkim zewnętrznym precyzyjnym linkom aktywowanie pojedynczego działania routera strażniczego, przeczytaj sekcję Obsługa działań związanych z routerem.

Przykład

Ten fragment kodu z przykładowego pliku shortcuts.xml pokazuje, jak dodać atrybut requiredForegroundActivity:

  <capability name="actions.intent.CREATE_TAXI_RESERVATION">
      <!-- Trigger with foreground app invocation if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
          <extra
              android:key="requiredForegroundActivity"
              android:value="com.example.app/com.example.app.MainActivity" />
      </intent>
      <!-- This won't trigger if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
      </intent>
  </capability>

Uprawnienia użytkownika

Aby wywoływanie aplikacji na pierwszym planie mogło działać dla użytkownika, musi on mieć włączone ustawienie Używaj tekstu na ekranie na urządzeniu. Lokalizacja i dokładna nazwa tego ustawienia mogą się różnić w zależności od producenta OEM lub producenta urządzenia. Ustawienie urządzenia może na przykład mieć nazwę Używaj kontekstu z ekranu na urządzeniu użytkownika.

Aby otworzyć to ustawienie Androida na telefonie Pixel, najpierw kliknij Ustawienia > Aplikacje i powiadomienia > Aplikacje domyślne > Aplikacja Asystent. Następnie na ekranie Asystent i wprowadzanie głosowe włącz Używaj tekstu na ekranie.

Testowanie wywołania

Aby wypróbować wywoływanie aplikacji na pierwszym planie, wykonaj te czynności:

1. Wykonaj instrukcje podane w sekcji Uprawnienia użytkownika, aby włączyć na urządzeniu ustawienie Używanie tekstu na ekranie.
2. Otwórz w aplikacji aktywność określoną jako wymaganą aktywność na pierwszym planie.
3. Naciśnij i przytrzymaj przycisk ekranu głównego, aby otworzyć Asystenta jako nakładkę w bieżącej aplikacji. Podaj zapytanie odpowiadające zaimplementowanemu przez Ciebie BII bez podawania nazwy aplikacji. Jeśli operacja się uda, aplikacja sama się zaktualizuje na podstawie zapytania, zachowując jej stan i bez ponownego uruchamiania aktywności.

Obsługa działań dotyczących routera

Niektóre aplikacje obsługują wszystkie zewnętrzne precyzyjne linki za pomocą jednej aktywności routera strażniczego. Działanie routera uruchamia wtedy odpowiednie działanie logiki biznesowej (po sprawdzeniu i weryfikacji), a następnie zwraca tę czynność na pierwszy plan.

Wywołanie precyzyjnego linku może spowodować dodanie aktywności routera na początku stosu zadań, nad aktywnością na pierwszym planie. W przypadku aplikacji, które używają routera, musisz się upewnić, że działanie routera odpowiada intencji wysłanej przez Asystenta Google do bieżącej instancji aktywności na pierwszym planie. Sposób osiągnięcia tego wymagania zmienia się w zależności od tego, gdzie rozpocznie się aktywność na routerze.

Jeśli router uruchamia się w tym samym stosie zadań co działanie logiki biznesowej, przekaż intencję za pomocą bitowej operacji LUB za pomocą funkcji SINGLE_TOP, CLEAR_TOP i NEW_TASK:

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK