Zintegruj akcje w aplikacji z widżetami na Androida

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
object MyAppWidget : AppWidgetProvider() {
    fun updateAppWidget(
        context: Context?,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
            .setResponseSpeech("Hello world") // TTS to be played back to the user
            .setResponseText("Hello world!") // Response text to be displayed in Assistant
            .build()

        // Update widget with TTS
        appActionsWidgetExtension.updateWidget(appWidgetId)

        // Update widget UI
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

  static void updateAppWidget(Context context, AppWidgetManager appWidgetManager,
    int appWidgetId) {

    AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
      .setResponseSpeech("Hello world")  // TTS to be played back to the user
      .setResponseText("Hello world!")  // Response text to be displayed in Assistant
      .build();

      // Update widget with TTS
      appActionsWidgetExtension.updateWidget(appWidgetId);

      // Update widget UI
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }

}

Rekomendacje dotyczące stylu TTS

Skorzystaj z podanych niżej zaleceń dotyczących stylu, aby zoptymalizować wprowadzenie do widżetu niestandardowego pod kątem zamiany tekstu na mowę i wyświetlanych promptów.

Przypinanie Menu z aplikacjami

Dzięki bibliotece rozszerzeń widżetów przycisk Dodaj ten widżet może być wyświetlany razem z widżetem w Asystencie. Aby włączyć przypinanie, dodaj do AndroidManifest.xml tę definicję odbiornika:

<application>
  <receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
    android:exported="false">
    <intent-filter>
      <action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
    </intent-filter>
  </receiver>
  <service
    android:name=
    "com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
      <action
        android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
    </intent-filter>
  </service>
</application>

Dostępność zasobów reklamowych

BII obsługujące wbudowane zasoby reklamowe lub internetowe zasoby reklamowe mogą rozszerzyć te zasoby o realizację widżetów.

Wbudowane zasoby reklamowe

Ten kod z przykładowego pliku shortcuts.xml pokazuje funkcję START_EXERCISE BII skonfigurowaną na potrzeby wbudowanych zasobów reklamowych i realizacji widżetów:

<capability
  android:name="actions.intent.START_EXERCISE">
  <app-widget
    android:identifier="START_EXERCISE_1"
    android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
    <parameter
      android:name="exercise.name"
      android:key="exerciseName"
      app:shortcutMatchRequired="true">
    </parameter>
  </app-widget>
</capability>

<shortcut android:shortcutId="RunningShortcut">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
  <capability-binding
    android:capability="actions.intent.START_EXERCISE"
    android:parameter="exercise.name"
    android:value="running;runs" />
</shortcut>

W poprzednim przykładzie, gdy użytkownik aktywuje tę funkcję, mówiąc do Asystenta: „Rozpocznij uruchamianie z przykładową aplikacją”, pakiet opcji realizacji <app-widget> zawiera tę parę klucz-wartość:

• Klucz = “exerciseName”
• Wartość = “RunningShortcut”

Zasoby reklamowe w internecie

Ten kod z przykładowego pliku shortcuts.xml pokazuje możliwość włączania zasobów reklamowych w internecie i realizacji widżetów:

<shortcuts>
  <capability
    android:name="actions.intent.START_EXERCISE">
    <app-widget
      android:identifier="START_EXERCISE_1"
      android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="exercise.name"
        android:key="exerciseName"
        android:mimeType="text/*">
        <data android:pathPattern="https://exampleapp.com/exercise/.*" />
      </parameter>
    </app-widget>
  </capability>
</shortcuts>

Testuj działania w aplikacji

Użyj narzędzia App Actions Test Tool, czyli funkcji wtyczki Asystenta Google do Android Studio, by przetestować widżety na urządzeniu fizycznym lub wirtualnym. Aby użyć narzędzia testowego, wykonaj te czynności:

1. Połącz urządzenie testowe z uruchomioną aplikacją.
2. W Android Studio wybierz Narzędzia > Działania w aplikacji > Narzędzie do testowania działań w aplikacji.
3. Kliknij Utwórz podgląd.
4. Użyj Android Studio, aby uruchomić aplikację na urządzeniu testowym.
5. Aby przetestować akcję w aplikacji, użyj aplikacji Asystent na urządzeniu testowym. Na przykład możesz powiedzieć „OK Google, ile mil przebyłeś w tym tygodniu w aplikacji ExampleApp?”.
6. Obserwuj działanie swojej aplikacji lub użyj debugera Android Studio, aby potwierdzić oczekiwane działanie.

Wskazówki dotyczące jakości

W tej sekcji omawiamy kluczowe wymagania i sprawdzone metody integrowania akcji w aplikacji z widżetami.

Treści w widżetach

• (Wymagane) Nie wyświetlaj reklam w widżecie.
• Skoncentruj się całkowicie na treści widżetu zgodnie z zamierzeniem. Nie próbuj realizować wielu intencji za pomocą jednego widżetu ani nie dodawaj nietrafnych treści.

Uwierzytelnienie

• (Wymagane) Jeśli do zakończenia działania użytkownika wymagane jest uwierzytelnianie użytkownika, zwracaj widżet wyjaśniający, że użytkownik musi kontynuować korzystanie z aplikacji. Wbudowane uwierzytelnianie użytkowników w Asystencie Google nie jest obsługiwane w przypadku Akcji dotyczących aplikacji.
• Jeśli użytkownicy zezwalają aplikacji na wyświetlanie danych za pomocą widżetów, możesz zwrócić widżet błędu w czasie działania w przypadku nieautoryzowanych użytkowników.

Intencje zastępcze

• (Wymagane) W obiekcie shortcuts.xml oprócz realizacji widżetu zawsze podaj też kreację zastępczą <intent> dla danej możliwości. Intencja zastępcza to element <intent> bez wymaganych wartości <parameter>.

  Dzięki temu Asystent może wykonać działanie, gdy zapytanie użytkownika nie zawiera parametrów wymaganych przez inne elementy realizacji zdefiniowane w funkcji. Wyjątkiem jest sytuacja, w której nie ma parametrów wymaganych do danej funkcji. W takim przypadku potrzebna jest tylko realizacja widżetu.

• Użyj intencji zastępczej, aby otworzyć aplikację na odpowiednim ekranie, a nie na ekranie głównym.

Ten kod z przykładowego pliku shortcuts.xml pokazuje element <capability> z wartością zastępczą <intent> obsługującą główną realizację <app-widget>:

<shortcuts>
  <capability
    android:name="actions.intent.CREATE_TAXI_RESERVATION">
    <!-- Widget with required parameter, specified using the "android:required" attribute. -->
    <app-widget
      android:identifier="CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="taxiReservation.dropoffLocation.name"
        android:key="dropoff"
        android:required="true">
      </parameter>
    </app-widget>
    <!-- Fallback intent with no parameters required to successfully execute. -->
    <intent
      android:identifier="CREATE_TAXI_RESERVATION_3"
      android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.TaxiReservationActivity">
    </intent>
  </capability>
</shortcuts>

Ujawnianie danych w Google Play

Ta sekcja zawiera informacje o tym, jakie dane użytkowników są zbierane przez najnowszą wersję biblioteki rozszerzeń widżetów.

Ten pakiet SDK wysyła udostępniane przez dewelopera odpowiedzi zamiany tekstu na mowę (TTS), które są wypowiadane użytkownikowi przez Asystenta Google przy użyciu technologii rozpoznawania mowy Asystenta. Te informacje nie są przechowywane przez Google.

Działania w aplikacji mogą też zbierać metadane aplikacji klienta w tych celach:

• Monitorowanie wskaźnika rozpowszechnienia różnych wersji pakietu SDK
• Aby sprawdzić wykorzystanie funkcji pakietu SDK w różnych aplikacjach