앱 작업과 Android 위젯 통합

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);
    }

}

TTS 스타일 권장사항

다음 스타일 권장사항을 참고하여 TTS 및 표시된 프롬프트의 맞춤 위젯 소개를 최적화하세요.

런처 고정

위젯 확장 프로그램 라이브러리를 사용하면 어시스턴트에서 위젯과 함께 이 위젯 추가 버튼을 표시할 수 있습니다. 고정을 사용 설정하려면 다음 수신기 정의를 AndroidManifest.xml에 추가하세요.

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

인벤토리 가용성

인라인 인벤토리 또는 웹 인벤토리를 지원하는 BII는 이러한 인벤토리를 위젯 처리로 확장할 수 있습니다.

인라인 인벤토리

샘플 shortcuts.xml 파일의 다음 코드는 인라인 인벤토리 및 위젯 처리를 위해 구성된 START_EXERCISE BII 기능을 보여줍니다.

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

이전 샘플에서는 사용자가 어시스턴트에 “ExampleApp으로 달리기 시작”을 요청하여 이 기능을 트리거하면 <app-widget> 처리의 선택적 번들에 다음 키-값 쌍이 포함됩니다.

• 키 = “exerciseName”
• 값 = “RunningShortcut”

웹 인벤토리

샘플 shortcuts.xml 파일의 다음 코드는 웹 인벤토리 및 위젯 처리를 위해 사용 설정된 기능을 보여줍니다.

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

앱 작업 테스트

Android 스튜디오용 Google 어시스턴트 플러그인 기능인 앱 작업 테스트 도구를 사용하여 실제 기기 또는 가상 기기에서 위젯을 테스트합니다. 테스트 도구를 사용하려면 다음 단계를 따르세요.

1. 테스트 기기를 실행 중인 앱과 연결합니다.
2. Android 스튜디오에서 Tools > App Actions > App Actions Test Tool로 이동합니다.
3. Create preview를 클릭합니다.
4. Android 스튜디오를 사용하여 테스트 기기에서 앱을 실행합니다.
5. 테스트 기기에서 어시스턴트 앱을 사용하여 앱 작업을 테스트합니다. 예를 들어 "Hey Google, 내가 ExampleApp에서 이번 주에 몇 km나 뛰었지?"라고 물어볼 수 있습니다.
6. 원하는 작업 결과인지 앱 동작을 관찰하거나 Android 스튜디오 디버거를 사용하여 확인합니다.

품질 가이드라인

이 섹션에서는 앱 작업을 위젯과 통합할 때의 핵심 요구사항과 권장사항을 중점적으로 설명합니다.

위젯 콘텐츠

• (필수) 위젯에는 광고를 표시해서는 안 됩니다.
• 위젯 콘텐츠를 인텐트를 처리하는 데 완전히 집중시킵니다. 위젯 하나로 여러 인텐트를 처리하거나 관련 없는 콘텐츠를 추가하려고 하지 마세요.

인증 처리

• (필수) 사용자 흐름을 완료하는 데 사용자 인증이 필요한 경우 사용자가 앱에서 계속 진행해야 함을 설명하는 위젯을 반환해야 합니다. Google 어시스턴트의 인라인 사용자 인증은 앱 작업에 지원되지 않습니다.
• 사용자가 위젯을 사용하여 앱에서 데이터를 표시하도록 허용하면 승인되지 않은 사용자에게 런타임에 오류 위젯을 반환할 수 있습니다.

대체 인텐트

• (필수) 위젯의 지정된 기능 처리 외에도 항상 대체 <intent>를 shortcuts.xml에 제공해야 합니다. 대체 인텐트는 필수 <parameter> 값이 없는 <intent> 요소입니다.

  그렇게 하면 기능에 정의된 다른 처리 요소에 필요한 매개변수가 사용자 쿼리에 포함되지 않은 경우에도 어시스턴트가 작업을 처리할 수 있습니다. 단, 그 기능에 필요한 매개변수가 없는 경우에는 예외입니다. 이 경우에는 위젯 처리만 필요합니다.

• 대체 인텐트를 사용하여 홈 화면이 아닌 관련 화면으로 앱을 엽니다.

샘플 shortcuts.xml 파일의 다음 코드는 기본 <app-widget> 처리를 지원하는 대체 <intent>가 있는 <capability>를 보여줍니다.

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

Google Play 데이터 공개

이 섹션에는 최신 버전의 위젯 확장 프로그램 라이브러리에서 수집된 최종 사용자 데이터가 나열되어 있습니다.

이 SDK가 개발자 제공 텍스트 음성 변환(TTS) 응답을 보내면 그 응답은 Google 어시스턴트가 어시스턴트의 음성 기술을 사용하여 사용자에게 알려줍니다. 이 정보는 Google에 저장되지 않습니다.

앱 작업에서는 다음 목적으로 클라이언트 앱 메타데이터를 수집할 수도 있습니다.

• 다양한 SDK 버전의 채택률 모니터링
• 앱 전반의 SDK 기능 사용량 수량화