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 memberikan jalur yang jelas dan sederhana kepada pengguna untuk 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 mengetahui 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 serta batasan yang mungkin Anda temui.

Prasyarat pengembangan

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

  • Perluas aplikasi Android Anda agar dapat menggunakan Action Aplikasi.

  • Sertakan com.google.android.googlequicksearchbox dalam tag <queries> di 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 menginstal hal berikut.

  • Versi terbaru aplikasi Google

  • Android 6.0 (level API 23) atau yang lebih tinggi

Batasan umum

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

Untuk menerapkan saran, Anda perlu mengupdate file build.gradle, menyiapkan klien saran, lalu menentukan saran yang ingin Anda berikan kepada pengguna.

  1. Tambahkan dependensi library ke file build.gradle Anda.

    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 contoh 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, secara opsional, apakah pintasan sudah ada.

    1. Buat intent pintasan aplikasi. Intent pintasan mewakili pintasan yang ingin Anda sarankan kepada pengguna. Contoh berikut membuat intent bagi pintasan untuk memulai latihan.

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

      Java

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

      Java

      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. 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 exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

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

      Java

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

      Dalam contoh ini, PHRASE adalah ucapan yang ingin Anda sarankan kepada pengguna sebagai pintasan. Misalnya, jika Anda ingin pengguna untuk mengucapkan "Ok Google, mulai berlari" sebagai pintasan, ganti PHRASE dengan "start a run".

      Kotlin

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

      Java

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .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.

Memecahkan masalah saran

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

"GoogleInstallationUnsupportedException: Tidak dapat mengikat ke layanan"

Karena pemfilteran visibilitas paket, "GoogleInstallationUnsupportedException: Tidak dapat mengikat ke layanan" 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.