인앱 프로모션 SDK를 사용하여 단축어 추천하기

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

사용자에게 어시스턴트 단축어를 추천하여 앱의 기능을 홍보하고 사용의 용이성을 높일 수 있습니다. 어시스턴트 단축어는 사용자가 앱 내에서 기능을 트리거하기 위해 말할 수 있는 간결한 구문입니다.

어시스턴트 단축어는 사용자가 직접 만들 수 있지만, 인앱 프로모션 SDK를 사용하여 사전에 어시스턴트 단축어를 구현하고 추천할 수 있습니다. 단축어를 추천하면 사용자는 단축어를 설정하기 위한 별도의 노력을 들이지 않고도 명확하고 간단한 경로를 통해 즐겨찾는 활동으로 돌아갈 수 있습니다.

예를 들어 사용자가 음악 앱에서 '헤비메탈 운동'을 검색할 경우 향후에 관련 검색결과에 어시스턴트 단축어를 바로 추천할 수 있습니다. 단축어를 추천하면 단축어에 관한 제안된 구문을 표시하고 사용자에게 단축어를 만들어야 할지 묻는 메시지가 앱에 표시됩니다. 이 예에서는 '내 헤비메탈 운동 시작'이라는 구문을 추천합니다. 사용자가 추천을 수락하면 "Hey Google, 내 헤비메탈 운동 시작해 줘"라고 말해 단축어를 실행할 수 있습니다.

앱 잠재고객을 늘리는 방법에 관한 자세한 내용은 앱 작업을 통해 앱 성장을 참고하세요.

인앱 프로모션 SDK는 다음 메서드를 제공합니다.

  • lookupShortcut은 추천할 단축어가 이미 있는지 확인합니다. 또한 이 메서드는 단축어 생성을 방해하는 문제가 있는지도 확인합니다. 단축어를 만들 수 없는 경우 LookupShortcut이 그 이유를 반환합니다.

  • createShortcutSuggestionIntent는 사용자에게 추천된 단축어를 만들라는 메시지를 표시하는 데 사용할 수 있는 인텐트를 반환합니다.

  • createShortcutSettingsIntent는 사용자를 앱의 어시스턴트 단축어 설정으로 이동시키는 데 사용할 수 있는 인텐트를 반환합니다.

전제 조건 및 제한사항

이 섹션에서는 추천 사용을 위한 기본 요건과 요구사항 그리고 생겨날 수 있는 제한사항을 설명합니다.

개발 기본 요건

추천을 사용하려면 개발 환경이 다음 기본 요건을 충족해야 합니다.

  • 앱 작업을 사용하도록 Android 앱이 확장되어야 합니다.

  • 매니페스트의 <queries> 태그 내에 com.google.android.googlequicksearchbox를 포함해야 합니다. 예:

    <manifest ...>
      <queries>
        <package android:name="com.google.android.googlequicksearchbox" />
      </queries>
      ...
    </manifest>
    
  • Android App Bundle을 사용하여 앱을 게시해야 합니다.

기기 요구사항

기기에서 추천을 테스트하려면 기기가 다음 요구사항을 충족해야 합니다.

  • 최신 버전의 Google 앱이 설치되어 있어야 합니다.

  • Android 버전은 M(API 수준 23) 이상이어야 합니다.

알려진 제한사항

이 섹션에서는 추천과 관련된 제한사항을 설명합니다.

추천은 영어로만 지원됩니다. 사용자가 개발자 추천을 보려면 기기의 어시스턴트 언어를 영어로 설정해야 합니다.

추천 구현

추천을 구현할 때 build.gradle 파일을 업데이트하고 추천 클라이언트를 설정한 후 사용자에게 제공할 추천을 정의해야 합니다.

앱에서 추천을 구현하는 방법은 다음과 같습니다.

  1. build.gradle 파일에 라이브러리 종속 항목을 추가합니다.

    dependencies {
      ...
      implementation "com.google.assistant.appactions:suggestions:1.0.0"
    }
    
  2. AssistantShortcutSuggestionsClient의 인스턴스를 정의합니다.

    Kotlin

    val shortcutsClient =
      AssistantShortcutSuggestionsClient.builder()
        .setContext(CONTEXT: Context)
        .setVerifyIntents(VERIFY_INTENTS: Boolean)
        .setCustomExecutor(CUSTOM_EXECUTOR: Object)
        .build()
    

    자바

    AssistantShortcutSuggestionsClient shortcutsClient =
      AssistantShortcutSuggestionsClient.builder()
        .setContext(CONTEXT: Context)
        .setVerifyIntents(VERIFY_INTENTS: Boolean)
        .setCustomExecutor(CUSTOM_EXECUTOR: Object)
        .build();
    

    여기서

    • CONTEXT(필수)는 애플리케이션 컨텍스트입니다.

    • VERIFY_INTENTS(필수)는 사용자에게 단축어를 제안할 때 생성된 모든 인텐트를 확인할지 결정합니다. true인 경우 AssistantShortcutSuggestionsClient에 의해 생성된 인텐트가 확인됩니다. 인텐트가 유효하지 않으면 예외가 반환됩니다.

    • CUSTOM_EXECUTOR(선택사항)는 비동기 작업을 실행하기 위한 맞춤 실행자입니다. 맞춤 실행자가 제공되지 않으면 SDK는 작업에 단일 스레드 실행자를 사용합니다.

  3. lookupShortcut 메서드를 사용하여 추천할 단축어가 유효한지 그리고 단축어가 이미 존재하는지 확인합니다. 기존 사용자 단축어를 확인할 계획이 없더라도 lookupShortcut을 구현하여, 추천으로 생성된 인텐트가 유효한지 확인하는 것이 좋습니다.

    1. 앱 바로가기 인텐트를 만듭니다. 바로가기 인텐트는 사용자에게 추천할 단축어를 나타냅니다. 다음 예에서는 사용자에게 음료를 주문하는 단축어를 설명합니다.

      Kotlin

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      자바

        Map menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .build();
       
    2. 바로가기 인텐트를 lookupShortcut 메서드에 전달합니다.

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
      if (!result.isShortcutPresent) {
          // app can suggest to create a shortcut
      } else {
          // app can remind that the user has a shortcut for this app action
      }
      

      자바

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // app can suggest to create a shortcut
          } else {
            // app can remind that the user has a shortcut for this app action
          }
        })
        .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
      
  4. 바로가기 인텐트를 사용하여 추천을 만듭니다.

    추천을 만드는 데 사용할 수 있는 메서드에는 두 가지가 있습니다.

    • createShortcutSuggestionIntent는 앱 컨텍스트에서 바로가기 추천 활동을 시작하는 데 사용하는 Android 인텐트를 반환합니다.

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build()
      
      val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
      application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
      

      자바

        AppShortcutSuggestion orderShortcut =
            AppShortcutSuggestion.builder()
                .setAppShortcutIntent(appShortcutIntent)
                .setCommand(PHRASE: String)
                .build();
      
        shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
            .addOnSuccessListener(intent ->
                getApplication().startActivity(
                    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
            )
            .addOnFailureListener(e ->
                Log.e(TAG, "Failed to get shortcut suggestion intent", e);
            );
      

      여기서 PHRASE는 사용자에게 단축어로 추천할 표현입니다. 예를 들어 사용자가 "Hey Google, 버블티 주문해 줘"를 단축어로 사용하여 말하도록 하려면 PHRASE"order my bubble tea"로 바꾸면 됩니다.

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand("order my bubble tea")
          .build()
      

      자바

      AppShortcutSuggestion orderShortcut =
          AppShortcutSuggestion.builder()
              .setAppShortcutIntent(appShortcutIntent)
              .setCommand("order my bubble tea")
              .build();
      
    • createShortcutSettingsIntent는 어시스턴트 앱의 단축어 설정 인터페이스로 사용자를 이동시키는 Android 인텐트를 반환합니다.

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
      application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
      

      자바

        shortcutsClient.createShortcutSettingsIntent()
          .addOnSuccessListener(intent ->
              getApplication().startActivity(
                  intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
          )
          .addOnFailureListener(e ->
              Log.e(TAG, "Failed to get shortcut settings intent", e);
          );
      
  5. 이전 단계에서 반환된 Android 인텐트를 사용하여 startActivity를 호출합니다.

    .

문제 해결 제안

이 섹션에는 바로가기를 추천할 때 발생할 수 있는 문제와 예외가 나열되어 있습니다.

GoogleInstallationUnsupportedException: 서비스에 바인딩할 수 없음

패키지 공개 상태 필터링으로 인해 GoogleInstallationUnsupportedException: Cannot bind to service가 Android 11 이상에서 발생할 수 있습니다. com.google.android.googlequicksearchbox가 매니페스트의 <queries> 태그 내에 포함되어 있는지 확인합니다.

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

'Failed to verify the APK signature'

프로덕션 앱을 App Bundle로 제출하지 않으면 다음과 같은 오류가 발생할 수 있습니다.

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

앱은 Android App Bundle로 제출해야 합니다.

'Failed to get user shortcuts'

최근에 기기에 계정을 추가했거나 새 계정의 바로가기 데이터가 아직 기기에 캐시되지 않은 경우 'Failed to get user shortcuts' 오류 메시지가 표시될 수 있습니다.

기기에서 바로가기 데이터를 동기화하려면 어시스턴트 앱의 인터페이스를 사용하여 어시스턴트 단축어를 추가하거나 삭제합니다.

콘텐츠를 표시하지 않고 바로가기 생성 작업이 즉시 닫힘

앱 작업 테스트 도구를 사용하여 미리보기를 만들지 않았거나 미리보기가 만료된 경우, 콘텐츠를 표시하지 않고 바로가기 생성 작업이 닫힐 수 있습니다. 미리보기를 업데이트하고 다시 시도합니다.