Menyarankan pintasan menggunakan SDK Promo Dalam Aplikasi

Untuk mempromosikan fitur aplikasi dan membuatnya lebih mudah digunakan, Anda dapat menyarankan pintasan Asisten kepada pengguna. Pintasan Asisten adalah frasa ringkas yang dapat diucapkan pengguna untuk memicu fungsi dalam aplikasi Anda.

Meskipun pintasan Asisten dapat dibuat secara manual oleh pengguna, SDK Promo dalam Aplikasi memungkinkan Anda secara proaktif menyarankan dan menerapkan pintasan Asisten. Dengan menyarankan pintasan, Anda memastikan pengguna memiliki jalur yang jelas dan sederhana kembali ke aktivitas favorit mereka di aplikasi Anda tanpa perlu upaya tambahan untuk menyiapkan pintasan.

Misalnya, jika pengguna melakukan penelusuran untuk "sesi olahraga iringan musik metal" di aplikasi musik Anda, sebaiknya sarankan pintasan Asisten langsung ke hasil penelusuran tersebut di masa mendatang. Saat Anda menyarankan pintasan, perintah akan muncul di aplikasi yang menampilkan frasa yang diusulkan untuk pintasan tersebut dan menanyakan pengguna apakah pintasan harus dibuat. Dalam contoh ini, Anda menyarankan frasa, "mulai sesi olahraga iringan musik metal saya". Pengguna menerima saran tersebut, kemudian dapat meluncurkan pintasan dengan mengucapkan,"Ok Google, mulai sesi olahraga iringan musik metal saya"

Untuk informasi selengkapnya tentang cara memperbanyak audiens aplikasi Anda, lihat Meningkatkan aplikasi dengan action aplikasi.

SDK Promo Dalam Aplikasi menyediakan metode berikut:

  • lookupShortcut memeriksa apakah pintasan yang ingin Anda sarankan sudah ada. Metode ini juga memeriksa masalah apa pun yang mencegah pintasan dibuat. Jika pintasan tidak dapat dibuat, LookupShortcut akan menampilkan alasannya.

  • createShortcutSuggestionIntent menampilkan intent yang dapat Anda gunakan untuk meminta pengguna membuat pintasan yang disarankan.

  • createShortcutSettingsIntent menampilkan intent yang dapat Anda gunakan untuk memindahkan pengguna ke setelan Pintasan Asisten untuk aplikasi Anda.

Prasyarat dan batasan

Bagian ini menjelaskan prasyarat dan persyaratan penggunaan saran, dan batasan yang mungkin Anda temui.

Prasyarat pengembangan

Untuk menggunakan saran, lingkungan pengembangan Anda harus memenuhi prasyarat berikut.

  • Pastikan aplikasi Android Anda diperluas untuk menggunakan Action Aplikasi.

  • Sertakan com.google.android.googlequicksearchbox dalam tag <queries> dalam manifes Anda. Contoh:

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

  • Gunakan Android App Bundle untuk memublikasikan aplikasi Anda.

Persyaratan perangkat

Untuk menguji saran di perangkat, perangkat Anda harus memenuhi persyaratan berikut.

  • Versi terbaru aplikasi Google telah diinstal.

  • Versi Android adalah M (API level 23) atau yang lebih baru.

Batasan umum

Bagian ini menjelaskan batasan terkait saran.

Saran hanya didukung dalam bahasa Inggris. Agar pengguna dapat melihat saran Anda, mereka harus menyetel bahasa Asisten di perangkat mereka ke bahasa Inggris.

Mengimplementasikan saran

Saat mengimplementasikan saran, Anda perlu memperbarui file build.gradle, menyiapkan klien saran, lalu menentukan saran yang ingin diberikan kepada pengguna.

Untuk menerapkan saran di aplikasi Anda:

  1. Tambahkan dependensi library ke file build.gradle.

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. Tentukan instance AssistantShortcutSuggestionsClient.

    Kotlin

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

    Java

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

    Dalam hal ini:

    • CONTEXT (wajib) adalah konteks aplikasi.

    • VERIFY_INTENTS (wajib) menentukan apakah akan memverifikasi setiap intent yang dibuat saat menyarankan pintasan kepada pengguna. Saat true, intent yang dibuat oleh AssistantShortcutSuggestionsClient akan diverifikasi. Jika intent tidak valid, pengecualian akan ditampilkan.

    • CUSTOM_EXECUTOR (opsional) adalah eksekutor kustom untuk menjalankan tugas asinkron. Jika tidak diberikan, SDK akan menggunakan eksekutor thread tunggal untuk tugas tersebut.

  3. Gunakan metode lookupShortcut untuk menentukan apakah pintasan yang ingin Anda sarankan valid dan apakah pintasan sudah ada. Sebaiknya terapkan lookupShortcut untuk memverifikasi bahwa intent yang dibuat oleh saran Anda valid, meskipun Anda tidak berencana memeriksa pintasan pengguna yang ada.

    1. Buat intent pintasan aplikasi. Intent pintasan mewakili pintasan yang ingin Anda sarankan kepada pengguna. Contoh berikut menjelaskan pintasan untuk memesan minuman kepada pengguna.

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

      Java

        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. Teruskan intent pintasan ke metode 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
}

      Java

      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. Buat saran menggunakan intent pintasan.

    Ada dua metode yang dapat digunakan untuk membuat saran:

    • createShortcutSuggestionIntent menampilkan intent Android yang Anda gunakan untuk memulai aktivitas saran pintasan dalam konteks aplikasi.

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

      Java

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

      Ketika PHRASE adalah ucapan yang ingin Anda sarankan kepada pengguna sebagai pintasan. Misalnya, jika Anda ingin pengguna mengucapkan "Ok Google, pesan teh boba saya" sebagai pintasan, Anda akan mengganti PHRASE dengan "order my bubble tea".

      Kotlin

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

      Java

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

    • createShortcutSettingsIntent menampilkan intent Android yang memindahkan pengguna ke antarmuka setelan pintasan di aplikasi Asisten.

      Kotlin

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

      Java

        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. Panggil startActivity menggunakan intent Android yang ditampilkan selama langkah sebelumnya.

Saran pemecahan masalah

Bagian ini mencantumkan masalah dan pengecualian yang mungkin Anda alami saat menyarankan pintasan.

GoogleInstallationUnsupportedException: Tidak dapat mengikat ke layanan

Karena pemfilteran visibilitas paket, GoogleInstallationUnsupportedException: Cannot bind to service dapat terjadi di Android 11 dan yang lebih baru. Pastikan com.google.android.googlequicksearchbox disertakan dalam tag <queries> dalam manifes Anda:

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

"Gagal memverifikasi tanda tangan APK"

Error berikut dapat terjadi jika Anda tidak mengirimkan aplikasi produktivitas sebagai 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.

Pastikan Anda mengirimkan aplikasi sebagai Android App Bundle.

"Gagal mendapatkan pintasan pengguna"

Pesan error "Gagal mendapatkan pintasan pengguna" dapat terjadi jika Anda baru saja menambahkan akun ke perangkat, dan jika data pintasan akun baru belum di-cache dalam perangkat.

Untuk menyinkronkan data pintasan di perangkat, tambahkan atau hapus pintasan Asisten menggunakan antarmuka aplikasi Asisten.

Aktivitas Pembuatan Pintasan langsung ditutup tanpa menampilkan konten apa pun

Aktivitas Pembuatan Pintasan dapat ditutup tanpa menampilkan konten jika Anda tidak membuat pratinjau menggunakan Alat Uji Action Aplikasi, atau jika pratinjau telah berakhir. Perbarui pratinjau, lalu coba lagi.