인앱 프로모션 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 6.0(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 메서드를 사용하여 추천할 단축어가 유효한지 그리고 단축어가 이미 존재하는지(선택 사항) 확인합니다.

    1. 앱 바로가기 인텐트를 만듭니다. 바로가기 인텐트는 사용자에게 추천할 단축어를 나타냅니다. 다음 예를 참고하세요. 바로가기에 대한 인텐트를 생성하여 운동을 시작합니다.

      Kotlin

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.START_EXERCISE")
    .setPackageName("my.app.package")
    .setIntentParamName("exercise")
    .setIntentParamValue(exercise)
    .build()

      자바

        Map exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .build();

    2. 바로가기 인텐트를 lookupShortcut 메서드에 전달합니다.

      Kotlin

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

      자바

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // App can suggest creating a shortcut
    } else {
      // App can remind the user that they have a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. 바로가기 인텐트를 사용하여 추천을 만듭니다. 추천을 만드는 데 사용할 수 있는 메서드에는 두 가지가 있습니다.

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

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

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

      자바

        AppShortcutSuggestion exerciseShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut)
      .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, 달리기 시작해 줘"라고 단축어로 말하면 "start a run"에서 PHRASE.

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      자바

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .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: Cannot bind to service'

패키지 공개 상태 필터링으로 인해 Android 11 및 이후 버전에서 'GoogleInstallationUnsupportedException: Cannot bind to service'가 발생할 수 있습니다. 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' 오류 메시지가 표시될 수 있습니다.

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

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

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